> For the complete documentation index, see [llms.txt](https://isciml.s2labs.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://isciml.s2labs.co/command-line-options/interactive-blocks.md).

# isciml: generate

## Overview

The `generate` subcommand in isciml is used for creating synthetic data or response files based on the models created with `generate-models`. This command is essential for generating electromagnetic field data, sensor responses, or synthetic measurements that can be used as input for AI models or simulations.

## Usage

### Sequential

```bash
singularity exec isciml.sif isciml generate [OPTIONS]
```

### Multiple Cores

```bash
singularity exec isciml.sif mpirun -np <NUMBER_OF_CORES> isciml generate [OPTIONS]
```

### Distributed

## Options

| Option                                   | Description                                                      | Default                 | Required |
| ---------------------------------------- | ---------------------------------------------------------------- | ----------------------- | -------- |
| `--vtk PATH`                             | Mesh in VTK file format                                          | -                       | Yes      |
| `--receiver_file PATH`                   | Receiver locations file in CSV format                            | -                       | Yes      |
| `--receiver_file_has_header`             | Flag to indicate if the receiver file has a header               | False                   | No       |
| `--perturb_receiver_z`                   | Flag to perturb receiver z location                              | False                   | No       |
| `--input_folder PATH`                    | Folder with files containing magnetic properties in numpy format | -                       | Yes      |
| `--ambient_field <FLOAT FLOAT FLOAT>...` | Ambient magnetic field values (x, y, z)                          | 820.5, 16241.7, 53380.0 | No       |
| `--output_folder PATH`                   | Folder for output files (adjoints or forward) in numpy format    | -                       | Yes      |
| `--output_prefix TEXT`                   | Prefix for output file names                                     | "adjoint" or "forward"  | No       |
| `--solver [adjoint, forward]`            | Solver mode: adjoint or forward                                  | adjoint                 | No       |
| `--help`                                 | Show the help message and exit                                   | -                       | No       |

## Description

The `generate` subcommand creates synthetic data based on the physical models and parameters you provide. It can operate in two modes: adjoint and forward, allowing for different types of data generation depending on your needs.

## Example Usage

To generate adjoint data with default settings:

```
singularity exec isciml.sif isciml generate \
    --vtk /path/to/mesh.vtk \
    --receiver_file /path/to/receivers.csv \
    --input_folder /path/to/magnetic_properties \
    --output_folder /path/to/output
```

To generate forward data with custom ambient field and output prefix:

```
singularity exec isciml.sif isciml generate \
    --vtk /path/to/mesh.vtk \
    --receiver_file /path/to/receivers.csv \
    --input_folder /path/to/magnetic_properties \
    --output_folder /path/to/output \
    --ambient_field 800 16000 53000 \
    --output_prefix custom_forward \
    --solver forward
```

##

## Notes

1. The VTK file should contain the mesh geometry created using the `generate-models` command.
2. The receiver file should be in CSV format, containing the locations of receivers.
3. If `--receiver_file_has_header` is not set, the CSV is assumed to have no header.
4. The `--perturb_receiver_z` option can be used to add some randomness to the z-coordinate of receivers, which may be useful for simulating real-world imperfections.
5. The input folder should contain files with magnetic properties (likely generated from `generate-models`).
6. The ambient field represents the background magnetic field in the x, y, and z directions.
7. Output files will be saved in the specified output folder, with names based on the input files and the chosen prefix.
8. The solver mode determines whether the command generates adjoint or forward data.

## Related Commands

* `generate-models`: Used to create the physical models before generating data.
* `train`: Used to train AI models on the generated data.
* `inference`: Used to apply trained models to new data.

### See Also

For more information on data generation techniques and parameters, refer to the isciml documentation on synthetic data creation and electromagnetic field modeling.