> 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/integrations.md).

# isciml: inference

## Overview

The `inference` subcommand in isciml is used for applying trained machine learning models to new data. This command allows users to use their trained models to make predictions on unseen samples, generating output that can be used for analysis or further processing.

## Usage

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

## Options

| Option                    | Description                          | Default                            | Required |
| ------------------------- | ------------------------------------ | ---------------------------------- | -------- |
| `--input_folder PATH`     | Folder containing input sample files | -                                  | Yes      |
| `--output_folder PATH`    | Folder for storing output files      | -                                  | Yes      |
| `--checkpoint_file PATH`  | Model checkpoint file                | -                                  | Yes      |
| \`--reshape\_base \[two   | eight]\`                             | Reshape 1D to 2D using base 2 or 8 | eight    |
| `--output_prefix TEXT`    | Prefix for output file names         | model\_output                      | No       |
| `--n_blocks INTEGER`      | Number of blocks in UNet             | 4                                  | No       |
| `--start_filters INTEGER` | Number of start filters              | 32                                 | No       |
| `--dim INTEGER`           | Dimension of the grid of solution    | 2                                  | No       |
| `--help`                  | Show the help message and exit       | -                                  | No       |

## Description

The `inference` subcommand allows you to apply a trained UNet model to new input data. It loads a trained model from a checkpoint file and processes the input samples to generate predictions. The predictions are then saved to the specified output folder.

## Example Usage

Basic usage with default settings:

```bash
singularity exec isciml.sif isciml inference \
    --input_folder /path/to/input_samples \
    --output_folder /path/to/output_predictions \
    --checkpoint_file /path/to/trained_model.ckpt
```

Advanced usage with custom settings:

```bash
singularity exec isciml.sif isciml inference \
    --input_folder /path/to/input_samples \
    --output_folder /path/to/output_predictions \
    --checkpoint_file /path/to/trained_model.ckpt \
    --reshape_base two \
    --output_prefix custom_prediction \
    --n_blocks 5 \
    --start_filters 64 \
    --dim 3
```

## Notes

1. The input folder should contain the sample files you want to make predictions on. These should be in the same format as the training samples used during the `train` command.
2. The output folder is where the prediction results will be saved. Each input file will have a corresponding output file.
3. The checkpoint file should be a saved model from a previous training session, typically created by the `train` command.
4. The `reshape_base` option determines how 1D input data is reshaped into 2D. This should match the setting used during training.
5. The `output_prefix` is prepended to each output file name. This can be useful for organizing different runs or model versions.
6. The `n_blocks` and `start_filters` options should match the architecture of the trained model. If you're unsure, use the same values that were used during training.
7. The `dim` option specifies the dimensionality of the solution grid. This should match the dimension of your input data and the model's architecture.
8. Ensure that the model architecture specified (`n_blocks`, `start_filters`, `dim`) matches the architecture of the trained model in the checkpoint file. Mismatched architectures will result in errors.

## Related Commands

* `generate-models`: Used to create the physical models.
* `generate`: Used to create the input data.
* `train`: Used to train the model that will be used for inference.

## See Also

For more information on model architectures, data formats, and interpretation of results, refer to the isciml documentation on machine learning models and data processing.