flashcart.cli

The console scripts call the entry points below. Use flashcart-train to train a potential, flashcart-test to evaluate a saved checkpoint, and flashcart-lammps to export a model for the ML-IAP interface. flashcart-profile measures model evaluation and differentiation on dataset batches. It constructs a model from the profiling configuration and does not perform optimizer updates.

Start with Quickstart for command examples. See Configuration files and overrides for configuration files and KEY=VALUE overrides, Run the profiler for profiling, and Export a model for model export.

Call train(), test(), and profile() from Python with configuration overrides. The main functions parse command-line arguments. For model export from Python, use the helpers in flashcart.calculators.

flashcart.cli.train

Train a FlashCart potential (the flashcart-train console script).

flashcart.cli.train.train(**overrides)

Initialize statistics, train the model, and evaluate its checkpoint.

Training resumes from the run’s saved state when available. After training, the best checkpoint is evaluated on the training and validation splits. The final checkpoint is used when no best checkpoint was saved.

Parameters:

**overrides – Config keys merged over flashcart/configs/default.yaml by load_config (model architecture, data paths and keys, losses, optimizer/scheduler, distributed and compile settings).

flashcart.cli.train.main()

CLI entry point: flashcart-train [CONFIG.yaml] [KEY=VALUE ...].

flashcart.cli.test

Evaluate a saved FlashCart model (the flashcart-test console script).

flashcart.cli.test.test(**overrides)

Evaluate a saved checkpoint on the configured validation and test datasets.

The model architecture comes from the checkpoint’s model_config.yaml. Evaluation settings come from the packaged defaults and supplied overrides. The checkpoint is selected by checkpoint or defaults to output_path/best. For older checkpoints without a model configuration, the model is reconstructed from the run’s config.yaml and applicable overrides.

Parameters:

**overrides – Configuration settings merged by load_config, including checkpoint or output_path, valid_path and test_path, valid_losses, reference-property keys, and device and compilation options.

Returns:

Mapping from each evaluated split name to its metric names and values.

Return type:

dict

Raises:

ValueError – No checkpoint location or evaluation dataset is specified, or an older checkpoint lacks the information needed to determine its elements.

flashcart.cli.test.main()

CLI entry point: flashcart-test [CONFIG.yaml] [KEY=VALUE ...].

flashcart.cli.profile

Profile FlashCart inference and training paths (the flashcart-profile script).

flashcart.cli.profile.profile(**overrides)

Measure prediction and differentiation costs for a newly initialized model.

Inference includes energy and force evaluation. The training phase includes prediction, loss evaluation, and differentiation with respect to model parameters. It does not perform optimizer steps. Data loading, neighbor-list construction, and device transfers take place before timing. Each timed run processes all selected batches. Reports include elapsed times and profiler operation tables, with optional trace files.

The model uses newly initialized weights and optional fitted data statistics rather than loading a checkpoint.

Parameters:

**overrides – Config keys merged over flashcart/configs/profile.yaml. Model and data keys are the training config keys. Profiling behavior is controlled by the profile_* keys listed there.

flashcart.cli.profile.main()

CLI entry point: flashcart-profile [CONFIG.yaml] [KEY=VALUE ...].

flashcart.cli.lammps_mliap

Export a training run for LAMMPS ML-IAP (the flashcart-lammps script).

flashcart.cli.lammps_mliap.main()

Export a run checkpoint for the LAMMPS ML-IAP interface.

flashcart-lammps RUN_DIR [best|log] [--compile-mode MODE] reads the selected checkpoint, using best by default, and writes RUN_DIR/flashcart-mliap.pt. The command prints the supported chemical elements. In the LAMMPS input, pair_coeff maps each LAMMPS atom type to one of these elements.

With --compile-mode, the export stores the selected compilation setting. FlashCart uses torch.compile when the model is first evaluated in LAMMPS. Modes using CUDA graphs are not supported by this interface. Without this option, evaluation is uncompiled. Exporting replaces an existing output file.