### Install Tensorpotential from Source

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Clones the grace-tensorpotential repository and installs the package locally. This is useful for developers or for using the latest unreleased features.

```bash
git clone https://github.com/ICAMS/grace-tensorpotential.git
cd grace-tensorpotential
pip install .
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/Foundation_models.ipynb

Imports necessary libraries for plotting, data manipulation, atomic structure building, and the GRACE calculator. Sets up the plotting environment.

```python
%pylab inline

import pandas as pd

from ase.build import bulk, molecule

from tensorpotential.calculator import grace_fm
```

--------------------------------

### Install Tensorpotential from PyPI

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Installs the tensorpotential package from the Python Package Index (PyPI). This is the standard way to install the library for general use.

```bash
pip install tensorpotential
```

--------------------------------

### Download GRACE Foundation Models

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Downloads pre-trained GRACE foundation models. These models are stored in the `$HOME/.cache/grace` directory.

```bash
grace_models download all
```

--------------------------------

### YAML Configuration for Presets

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/presets.md

Example of how to select a preset and pass keyword arguments in the input.yaml file. This configuration section defines the potential model to be used.

```yaml
potential:
  # LINEAR, FS, GRACE_1LAYER, GRACE_2LAYER
  preset: "FS" 
  
  # kw-arguments that will be passed to preset or custom function
  kwargs: {n_rad_base: 16, embedding_size: 64}
```

--------------------------------

### GRACE/FS (CPU) Installation

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Installs the standalone C++ implementation of GRACE/FS. This version does not require TensorFlow and can be parallelized with MPI.

```bash
conda activate grace
git clone -b feature/grace_fs https://github.com/ICAMS/python-ace.git
cd python-ace
pip install .
pip install cmake
```

--------------------------------

### Micromamba Environment Setup

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Installs micromamba and creates/activates a new conda environment named 'grace' with Python 3.11. This is the recommended method for managing environments.

```bash
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)
micromamba create -n grace python=3.11 
micromamba activate grace
```

--------------------------------

### GRACE Model Parameterization Tool

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Starts the GRACE model parameterization process. The tool creates a working subfolder for each seed, containing logs, metrics, checkpoints, and model configuration files.

```bash
gracemaker
```

--------------------------------

### Install TensorFlow with GPU Support

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Manually installs TensorFlow with CUDA support for GPU acceleration. Ensure your system meets TensorFlow's GPU requirements.

```bash
pip install tensorflow[and-cuda]==2.16.2
```

--------------------------------

### Fine-tuning Optimization Parameters

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/foundation.md

Example `fit` section in `input.yaml` demonstrating recommended settings for fine-tuning foundation models. This includes setting a small learning rate and enabling initial metric evaluation.

```yaml
fit:

  # set small learning rate
  opt_params: {learning_rate: 0.001,  ... }
  
  # evaluate initial metrics
  eval_init_stats: True
```

--------------------------------

### grace_models CLI

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/utilities.md

Utility to download GRACE foundation models. It provides sub-commands to list available models and download specific ones. Usage examples are provided for clarity.

```APIDOC
grace_models [-h] {list,download} ...

Download foundational GRACE models

Positional Arguments:
  {list,download}  Sub-command help
    list           List available models
    download       Download a model

Options:
  -h, --help       show this help message and exit

Example:
```bash
grace_models
```
```

--------------------------------

### YAML Configuration for Fine-tuning

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/foundation.md

Example `input.yaml` configuration snippet to specify a foundation model for fine-tuning. It includes settings for the foundation model and optional parameters like `reduce_elements`.

```yaml
potential:
  finetune_foundation_model: GRACE-1L-OAM
#  reduce_elements: True # if True - select from original models only elements presented in the CURRENT dataset
```

--------------------------------

### Anaconda Environment Setup

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Creates and activates a new conda environment named 'grace' with Python 3.11. Note that Anaconda has specific licensing conditions.

```bash
conda create -n grace python=3.11
conda activate grace
```

--------------------------------

### Configure GRACE Model Fine-Tuning (yaml)

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Provides examples of YAML configuration snippets for fine-tuning GRACE foundation models. It shows how to specify the model to finetune, learning rate, and evaluation settings, as well as how to manually specify model and checkpoint file paths.

```yaml
potential:
  finetune_foundation_model: GRACE-1L-OAM
#  reduce_elements: True # select from original models only elements presented in the dataset  
fit:

  # set small learning rate
  opt_params: {learning_rate: 0.001,  ... }
  
  # evaluate initial metrics
  eval_init_stats: True
  
  # reset_optimizer: True
```

```yaml
potential:
  filename: /path/to/model.yaml
  checkpoint_name: /path/to/checkpoints/checkpoint.best_test_loss
#  reduce_elements: True 
```

--------------------------------

### LAMMPS Multi-GPU Parallelization Example

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Shell command example for running LAMMPS with GRACE models on multiple GPUs using MPI. It assigns GPUs based on MPI rank and sets TensorFlow logging level.

```bash
TF_CPP_MIN_LOG_LEVEL=1 mpirun -np 4 --bind-to none  bash -c 'CUDA_VISIBLE_DEVICES=$((OMPI_COMM_WORLD_RANK % 4)) lmp -in in.lammps'
```

--------------------------------

### LAMMPS Compilation

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Compiles the LAMMPS simulation package after CMake configuration. The `-j 8` flag specifies using 8 parallel jobs for faster compilation.

```bash
cmake --build . -- -j 8
```

--------------------------------

### Run LAMMPS Simulation with GRACE/FS

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Executes a LAMMPS simulation using a GRACE/FS compiled version. The example simulates an FCC(111) surface slab under NPT conditions with increasing temperature and computes extrapolation grades.

```bash
cd 3-lammps/grace-fs-with-extrapolation-grade/
mpirun -np 2 /path/to/lmp -in in.lammps
```

--------------------------------

### Register User-Defined Models

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/foundation.md

Example content for `$HOME/.cache/grace/models_registry.yaml` to add user-defined models to the local registry. It specifies the path to the model and checkpoint files.

```yaml
MODEL-NAME:
  path: /path/to/saved_mode
  checkpoint_path: /path/to/checkpoint/  # model.yaml and checkpoint.index should be in this folder
  description: some description
  license: some license
```

--------------------------------

### LAMMPS CMake Configuration

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Configures the LAMMPS build with ML-PACE and MC packages, enabling TensorFlow support. This command prepares LAMMPS for compilation with GRACE integration.

```APIDOC
cmake -DCMAKE_BUILD_TYPE=Release -D BUILD_MPI=ON -DPKG_ML-PACE=ON -DPKG_MC=ON ../cmake
# Ensure 'TensorFlow library is FOUND at ...' appears in output.
```

--------------------------------

### GRACE 1Layer Calculator Usage

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/Foundation_models.ipynb

Initializes the GRACE 1-layer calculator, creates a bulk Tungsten (W) structure, applies thermal vibrations, assigns the calculator, and computes the total potential energy and forces.

```python
calc=grace_fm('mp-1layer')
at=bulk("W", cubic=True)*(2,2,2)
at.rattle(stdev=0.1,seed=42)
at.calc=calc

# Calculate total potential energy
print(f"Total Potential Energy (1-layer): {at.get_potential_energy()}")

# Calculate potential energy per atom
print(f"Potential Energy per Atom (1-layer): {at.get_potential_energy()/len(at)}")

# Calculate forces
print(f"Forces (1-layer): {at.get_forces()}")
```

--------------------------------

### GRACE 2Layer Calculator Usage

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/Foundation_models.ipynb

Initializes the GRACE 2-layer calculator, creates a bulk Tungsten (W) structure, applies thermal vibrations, assigns the calculator, and computes the total potential energy and forces.

```python
calc=grace_fm('mp-2layer')
at=bulk("W", cubic=True)*(2,2,2)
at.rattle(stdev=0.1,seed=42)
at.calc=calc

# Calculate total potential energy
print(f"Total Potential Energy (2-layer): {at.get_potential_energy()}")

# Calculate potential energy per atom
print(f"Potential Energy per Atom (2-layer): {at.get_potential_energy()/len(at)}")

# Calculate forces
print(f"Forces (2-layer): {at.get_forces()}")
```

--------------------------------

### Get GRACE Model Summary using grace_utils

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/utilities.md

Prints a summary of the GRACE model using the grace_utils command. The verbosity level can be controlled using the `-v` flag, with 0 being least verbose and 2 being most verbose.

```bash
grace_utils -p /path/to/model.yaml summary -v 1
```

--------------------------------

### Load GRACE Foundation Model with grace_fm

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Loads a GRACE foundation model using the `grace_fm` function. This provides an easy way to access pre-trained models for use with ASE, simplifying the setup process.

```python
from tensorpotential.calculator import grace_fm

calc = grace_fm('name_of_the_model')
```

--------------------------------

### Navigate to Tutorial 1 Folder

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Changes the current directory to the working folder for Tutorial 1, which focuses on the parameterization of a 2-layer GRACE potential for Al-Li.

```bash
cd 1-AlLi-GRACE-2LAYER
```

--------------------------------

### Clone GRACE Tutorial Repository

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Clones the GRACE tutorial repository from GitHub. This command downloads all necessary files and scripts for the tutorials, providing a local copy for offline use and modification.

```bash
git clone --depth=1 https://github.com/ICAMS/grace-tutorial
```

--------------------------------

### Navigate to Tutorial 2 Folder

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Changes the current directory to the working folder for Tutorial 2, which focuses on the parameterization of GRACE/FS for a high entropy alloy (HEA25S) dataset.

```bash
cd grace-tutorial/2-HEA25S-GRACE-FS/
```

--------------------------------

### Run Gracemaker Model Training

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Executes the gracemaker model training process using a specified input configuration file. Warning messages related to JIT compilation are normal and indicate the process is underway.

```bash
gracemaker input.yaml
```

--------------------------------

### Download GRACE Foundation Models (bash)

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Downloads a specified GRACE foundation model or all available models. This is a prerequisite for using the models in simulations. The 'all' keyword downloads the entire collection.

```bash
grace_models download MP_GRACE_1L_r6_4Nov2024
```

```bash
grace_models download all
```

--------------------------------

### List Available GRACE Foundation Models (bash)

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Lists all the GRACE foundation models that are available for download. This command helps users identify the specific model names they can use for their simulations.

```bash
grace_models list
```

--------------------------------

### Run Gracemaker Parameterization

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Executes the GRACE model parameterization process using the generated `input.yaml` file. This involves data preprocessing, JIT compilation, and training the potential.

```bash
gracemaker
```

--------------------------------

### Interactive Gracemaker Parameterization

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Initiates an interactive dialogue to configure the gracemaker model parameters. It prompts for essential inputs like dataset filenames, model presets, complexity, and loss function weights.

```bash
cd 1-fit 
gracemaker -t
```

--------------------------------

### LAMMPS CMake Configuration (No TensorFlow)

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/install.md

Configures the LAMMPS build with ML-PACE and MC packages, explicitly disabling TensorFlow support. Use this if you only need exported GRACE/FS models.

```APIDOC
cmake -DCMAKE_BUILD_TYPE=Release -D BUILD_MPI=ON -DPKG_ML-PACE=ON -DNO_GRACE_TF=ON ../cmake
```

--------------------------------

### Unpack DFT Data

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Extracts the VASP DFT data archive for Tutorial 1. This prepares the raw data files required for the GRACE parameterization process.

```bash
cd 0-data
tar zxvf AlLi_vasp_data.tar.gz
```

--------------------------------

### Continue Gracemaker Fit with New Parameters

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Allows resuming a previous gracemaker training session with modified parameters, such as adjusting loss function weights or learning rates. Requires copying existing configuration and checkpoints to a new directory.

```bash
cd ..
mkdir -p 1b-continue-fit 
cp 1-fit/input.yaml 1b-continue-fit/
mkdir -p 1b-continue-fit/seed/1
cp -r 1-fit/seed/1/checkpoints 1b-continue-fit/seed/1/
cd 1b-continue-fit/
gracemaker -r
```

--------------------------------

### Gracemaker Configuration File Structure

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Defines the structure and key parameters for the gracemaker input configuration file. This includes settings for the fitting process, loss functions, and optimization parameters.

```APIDOC
fit:
  loss: {
    energy: {weight: <float>, type: <string>, delta: <float>},
    forces: {weight: <float>, type: <string>, delta: <float>},
    stress: {weight: <float>, type: <string>, delta: <float>},
    switch: <list_of_switches> # Optional: for dynamic loss switching
  }

  opt_params: {
    learning_rate: <float>,
    # ... other optimization parameters
  }
  
  learning_rate_reduction: {
    # ... settings for learning rate decay
    resume_lr: <boolean> # If true, resumes LR from checkpoint
  }

# ... other configuration sections
```

--------------------------------

### Generate Gracemaker Input File

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Generates the `input.yaml` configuration file for `gracemaker` by running the tool with the `-t` flag. This interactive process prompts the user for various model parameters and dataset details.

```bash
cd ../1-fit
gracemaker -t
```

--------------------------------

### Construct Active Set for Uncertainty Indication

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Builds the active set (ASI) for uncertainty indication, which is crucial for active learning strategies in GRACE/FS. It requires the training set and the trained model file.

```bash
cd seed/1
pace_activeset -d training_set.pkl.gz FS_model.yaml
```

--------------------------------

### Collect DFT Data with grace_collect

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Runs the `grace_collect` utility to recursively gather and process DFT data. This step generates a `collected.pkl.gz` file, which serves as the input for the `gracemaker` tool.

```bash
grace_collect
```

--------------------------------

### Import OS Module

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Imports the os module, which provides a way to interact with the operating system, such as accessing environment variables.

```python
import os
```

--------------------------------

### Run Gracemaker with Different Seeds

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Initiates multiple GRACE parameterization runs with different random seeds to create an ensemble of models. This is useful for improving model robustness and exploring parameter space.

```bash
gracemaker --seed 2
gracemaker --seed 3
```

--------------------------------

### Select Representative Structures using Pace Select

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Selects representative structures from simulation dump files for DFT calculations based on D-optimality. It requires the dump file, the trained model's YAML and ASI files, and optionally an element filter.

```bash
pace_select extrapolative_structures.dump  -p ../../1-fit/seed/1/FS_model.yaml -a ../../1-fit/seed/1/FS_model.asi -e "Au"
```

--------------------------------

### Import Tensorpotential Utilities

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Imports all functions and classes from the 'utils' submodule within the 'tensorpotential' package. This grants access to custom project-specific functionalities.

```python
from tensorpotential.utils import *
```

--------------------------------

### GRACE Bucketing Explanation

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/faq.md

Explanation of `train_max_n_buckets` and `test_max_n_buckets` parameters in GRACE models. These parameters control batch splitting and padding for JIT compilation efficiency, aiming to minimize padding overhead.

```APIDOC
GRACE Bucketing Parameters:

`train_max_n_buckets`
  - Description: Maximum number of buckets for padding training data.
  - Purpose: Improves efficiency of JIT-compiled GRACE models by splitting batches into similarly sized buckets to reduce padding.
  - Recommendation: Monitor `[TRAIN] dataset stats:` log for padding percentage (aim below 15%).

`test_max_n_buckets`
  - Description: Maximum number of buckets for padding testing data.
  - Purpose: Similar to `train_max_n_buckets`, but for testing data.
  - Recommendation: Monitor `[TEST] dataset stats:` log for padding percentage (aim below 15%).

Example Log Line:
  [TRAIN] dataset stats: num. batches: 18 | num. real structures: 576 (+2.78%) | num. real atoms: 10942 (+5.25%) | num. real neighbours: 292102 (+1.74%)
```

--------------------------------

### Multi-GPU Fit Configuration

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/faq.md

Guidance on performing multi-GPU fitting for GRACE models. The `-m` option enables data-parallel fitting, requiring an adjustment to the global batch size.

```bash
# Use the -m option for data-parallel fitting on multi-GPU nodes:
# gracemaker ... -m

# When using -m, increase the global batch size for better utilization.
```

--------------------------------

### Define List of Folders

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Defines a Python list containing several directory paths. These paths likely point to locations where experimental or simulation data, relevant to fitting, is stored.

```python
folders = [
    "/home/users/bochkanl/Documents/Work/HEA/HME21/HME21-CE-downscale_12/config3/new_ema/seed/2",
    "/home/users/bochkanl/Documents/Work/HEA/HME21/HME21-CE-downscale_12/config3/new_ema/diff_init/seed/22",
    "/home/users/bochkanl/Documents/Work/HEA/HME21/HME21-CE-downscale_12/config3/new_ema/diff_init_1/seed/22",
    "/home/users/bochkanl/Documents/Work/HEA/HME21/HME21-CE-downscale_12/config3/new_ema/seed/22",
    "/home/users/bochkanl/Documents/Work/HEA/HME21/HME21-CE-downscale_12/config3/seed/2"
    
]
```

--------------------------------

### Download GRACE Model Checkpoint

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/foundation.md

Downloads a checkpoint for a specific GRACE foundation model. Checkpoints are required for fine-tuning and are automatically downloaded when needed.

```bash
grace_models checkpoint <MODEL-NAME>
```

--------------------------------

### List Available GRACE Models

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/foundation.md

Lists all available pre-trained GRACE foundation models. This command is essential for users to identify models before downloading or fine-tuning.

```bash
grace_models list
```

--------------------------------

### Restart GRACE Fit

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/faq.md

Instructions on how to restart a GRACE model fitting process from previous checkpoints. This allows for resuming interrupted training or continuing from the best-performing state.

```bash
gracemaker -r
# Restarts from the previous best-test-loss checkpoint.
```

```bash
gracemaker -rl
# Restarts from the latest checkpoint.
```

```bash
# To continue in a new folder, copy checkpoints and model.yaml:
# cp seed/{number}/checkpoints new_folder/
# cp seed/{number}/model.yaml new_folder/
```

--------------------------------

### grace_utils CLI - Model Management

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/utilities.md

A comprehensive CLI tool for managing GRACE models, including updating, reducing elements, changing precision, exporting, and summarizing. It handles model format conversions and complexity reduction.

```APIDOC
grace_utils [-h] -p POTENTIAL [-c CHECKPOINT_PATH] [-os OUTPUT_SUFFIX] {update_model,reduce_elements,cast_model,export,summary} ...

CLI tool for model conversions and summarization

Positional Arguments:
  {update_model,reduce_elements,cast_model,export,summary}
    update_model        Update model (model.yaml) and corresponding checkpoint.
    reduce_elements     Reduce elements from the model.
    cast_model          Change model's floating point precision.
    export              Export model to saved_model or FS/C++ format.
    summary             Show info about the model

Options:
  -h, --help            show this help message and exit
  -p POTENTIAL, --potential POTENTIAL
                        Path to model.yaml
  -c CHECKPOINT_PATH, --checkpoint-path CHECKPOINT_PATH
                        Path to checkpoint
  -os OUTPUT_SUFFIX, --output-suffix OUTPUT_SUFFIX
                        Output suffix for converted

Sub-command Specific Options:

update_model:
  No additional options.

reduce_elements:
  -e ELEMENTS [ELEMENTS ...], --elements ELEMENTS [ELEMENTS ...]
                        Elements to select

cast_model:
  -curr {fp32,fp64}  Current precision type to cast from
  -to {fp32,fp64}    New precision type to cast into

summary:
  -v {0,1,2}, --verbose {0,1,2}
                        Verbosity level: 0, 1 or 2

Usage Examples:

Update models (for gracemaker < 0.5 compatibility):
```bash
grace_utils -p /path/to/model.yaml -c /path/to/checkpoint/checkpoint.best_test_loss.index  -os dict update_model
```

Reduce model's chemical complexity (e.g., select Mo, Nb, Ta, W):
```bash
grace_utils -p /path/to/model-dict.yaml -c /path/to/checkpoint/checkpoint-dict.index  -os MoNbTaW reduce_elements -e Mo Nb Ta W
```

Change model's floating point precision (e.g., single to double):
```bash
grace_utils -p /path/to/model.yaml -c /path/to/checkpoint.index -os "double" cast_model -curr fp32 -to fp64
```
```

--------------------------------

### Data Collection Utility

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Initiates the data collection process using the grace_collect utility. This is a command-line tool for gathering necessary data for model parameterization.

```bash
grace_collect
```

--------------------------------

### Load GRACE Foundation Model in ASE (python)

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Demonstrates how to load a GRACE foundation model as a calculator within the Atomic Simulation Environment (ASE). It shows the primary function `grace_fm` and optional parameters for customization, including using an enum for model selection.

```python
from tensorpotential.calculator.foundation_models import grace_fm, GRACEModels

calc = grace_fm("MP_GRACE_1L_r6_4Nov2024",
                pad_atoms_number=2,
                pad_neighbors_fraction=0.05,
                min_dist=0.5)
# or 
calc = grace_fm(GRACEModels.MP_GRACE_1L_r6_4Nov2024) # for better code completion
```

--------------------------------

### Convert extxyz Dataset to Pandas DataFrame

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Converts datasets from extxyz format to a compressed pandas DataFrame (.pkl.gz) using the extxyz2df utility. This is a preliminary step for preparing training data.

```bash
unzip data.zip
cd data/dataset_O_bulk_random
extxyz2df bulk_random_train.xyz
```

--------------------------------

### Run LAMMPS Simulation with GRACE Potential

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Executes a LAMMPS simulation using a GRACE potential. This requires LAMMPS to be compiled with GRACE support and specifies the path to the SavedModel and the elements involved.

```bash
cd ../3-lammps/
/path/to/lmp -in in.lammps
```

--------------------------------

### Download GRACE Foundation Model

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/foundation.md

Downloads a specific pre-trained GRACE foundation model by its name. Models are typically stored in the `$HOME/.cache/grace` directory by default.

```bash
grace_models download <model_name>
```

--------------------------------

### GRACE Model Configuration for Restart

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Specifies the model and checkpoint files to use when restarting the GRACE model parameterization process via an input YAML file.

```yaml
potential:
  filename: /path/to/model.yaml
  checkpoint_name: /path/to/chekpoint.index
```

--------------------------------

### FIT Configuration Parameters

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/inputfile.md

Defines the core parameters for the fitting process, including loss function configurations (e.g., Huber, square), optimizer settings (Adam, L-BFGS-B), learning rate reduction strategies, batch sizes, and JIT compilation options for XLA.

```yaml
fit:
  loss: {
    energy: { type: huber, weight: 1,  delta: 0.1  }, # or { type: square, weight: 1}
    forces: { type: huber, weight: 5., delta: 0.01 },
  # stress: { type: huber, weight: 0.1},   #

  ## Change weights for energy/forces/stress loss components
  ## and learning_rate after "after_iter" epochs
  #    switch: { after_iter: 350,
  #              energy: { weight: 5.0 },
  #              forces: { weight: 2.0 },
  #              stress: {weight: 0.001},
  #               learning_rate: 0.001}

  # l2_reg: 1.0e-10  ## L2-regularization not used
  }

  maxiter: 500 # Max number of iterations

  ## Optimization with Adam: good for large number of parameters, first-order method
  optimizer: Adam
  opt_params: { learning_rate: 0.01, amsgrad: True, use_ema: True, ema_momentum: 0.99,  weight_decay: 1.e-20, clipvalue: 1.0}
  # reset_optimizer: True  # reset optimizer, after being loaded from checkpoint
  # for learning-rate reduction
  learning_rate_reduction: { patience: 5, factor: 0.98, min: 5.0e-4, stop_at_min: True, resume_lr: True, }

  ## Optimization with BFGS: good for SMALL number of parameters (up to 10k), "second"-order method.
  ## scipy optimizer on CPU will be used
  #  optimizer: L-BFGS-B # 'L-BFGS-B' for memory limited or 'BFGS' for full method
  #  opt_params: {maxcor: 100, maxls: 20 }  # options for L-BFGS-B


  batch_size: 32 # Important hyperparameter for Adam and irrelevant (but must be) for L-BFGS-B/BFGS
  test_batch_size: 200 # test batch size (optional)


  ## Uniform weighting is used if not specified
  ## Energy based weighting can be used as:  
  #  weighting: {type: energy_based}  # the simplest default

  # compute_convex_hull: False ## for train+test dataset compute convex hull and distance to it 
  # eval_init_stats: False  ## Compute train/test metrics before start fitting 

  jit_compile: True  # for XLA compilation, must be used in almost all cases
  ## To use jit_compile efficiently, data must be padded.
  ## Bucket is a group of batches padded to the same shape
  train_max_n_buckets: 10  ## max number of buckets in train set  
  test_max_n_buckets: 3  ## same for test

  checkpoint_freq: 10 # frequency for **REGULAR** checkpoints. 
  # save_all_regular_checkpoints: False # to store ALL regular checkpoints
  # progressbar: True # show batch-evaluation progress bar
  # train_shuffle: True # shuffle train batches on every epoch
  # strategy: mirrored # or -m flag # for parallel multi-GPU parameterization

  ## technical parameters for normalization
  #  loss_norm_by_batch_size: False # normalization of total loss by global batch size (for backward compat)
  #  normalize_weights: True ## norm per-sample weights to sum-up to one
  #  normalize_force_per_structure: True ## force-weights is divided by number of atoms

```

--------------------------------

### Building Active Set for GRACE/FS

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Generates an active set (ASI) file for GRACE/FS models to compute extrapolation grade using D-optimality. Requires the `python-ace` library and is typically run from within the model's working directory.

```bash
cd seed/1
pace_activeset -d training_set.pkl.gz FS_model.yaml
```

--------------------------------

### GRACE Configuration Options

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/faq.md

Details on configuring GRACE models, including checkpoint frequency and bond-specific cutoffs. These settings influence how the model saves progress and handles different atomic interactions.

```yaml
# Specify checkpoint frequency (saves only the last state):
# checkpoint_freq: <frequency_in_steps>

# Keep all regular checkpoints:
# input.yaml::fit::save_all_regular_checkpoints: True
```

```yaml
# Specify bond-specific cutoffs:
# cutoff_dict: {Mo: 4, MoNb: 3, W: 5, Ta*: 7}
# This can be used alongside the general 'cutoff' option.
```

--------------------------------

### Grace Tensorpotential input.yaml Configuration

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/inputfile.md

This YAML file defines the input parameters for the Grace Tensorpotential project. It includes settings for data loading, such as filenames and reference energies, and configurations for the potential model, including presets, custom models, and fine-tuning options. It also specifies other operational parameters like random seeds and cutoff values.

```yaml
seed: 42
cutoff: 6

# cutoff_dict: {Mo: 4, MoNb: 3, W: 5, Ta*: 7 } ## Defining cutoff for each bond type separately, used by certain models
## possible defaults: DEFAULT_CUTOFF_1L, DEFAULT_CUTOFF_2L

######################
##       DATA       ##
######################
data:
  filename: /path/to/train.pckl.gzip
  #  train_size: 100
  test_filename: /path/to/test.pckl.gzip
  #  test_size: 0.05 # 
  reference_energy: 0 
  # reference_energy: {Al: -1.23, Li: -3.56}
  # save_dataset: False # default is True
  # stress_units: eV/A3 # eV/A3 (default) or GPa or kbar or -kbar
  # max_workers: 6 # for parallel data builder

######################
##    POTENTIAL     ##
######################
potential:
  #  elements: [C, H, O] # If not provided - determined automatically from data


  ## Option 1. Presets
  preset: GRACE_1LAYER # FS, GRACE_1LAYER, GRACE_2LAYER
  # kwargs: {n_rad_max: 16}  # kw-arguments that will be passed to preset or custom model

  ## Option 2. Custom model in python file (advanced)
  # custom: model.custom_model # custom model from model.py file, function custom_model



  ## Option 3. Model in model.yaml
  # filename: model.yaml # configuration (WITHOUT weights!) of the model
  # checkpoint_name: /path/to/checkpoint.index  #  path to checkpoint index file  


  ## Option 4. Fine-tune foundation model
  # finetune_foundation_model: GRACE-1L-OAM
  # reduce_elements: True #  default - False, reduce elements to those provided in dataset

  ## Other parameters: 
  # shift: False # True/False - automatic shift by energy
  # scale: False # False/True or float  - automatic scale data by force RMSE
  # avg_n_neigh: 40 # Average number of neighbours. By default - automatically determined
  #  float_dtype: float64 # float64, float32
  #  custom ZBL core repulsion for model:  kwargs: {zbl_cutoff: {Mo: 1, MoNb: 2, W: 1, Ta*: 3 }}

######################

```

--------------------------------

### Initialize Fit Dictionary

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Initializes an empty dictionary named 'fit_dict'. This dictionary is intended to store and manage data related to various fits or experiments.

```python
fit_dict={}
```

--------------------------------

### Gracemaker Command-Line Interface

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/cli.md

This section details the command-line interface for Gracemaker, a utility designed for fitting graph atomic cluster expansion potentials. It outlines the available arguments, their purpose, and default values, enabling users to configure and execute fitting processes. The tool supports various options for logging, distributed computing, restarting fits, specifying potential configurations, and exporting models.

```APIDOC
gracemaker [-h] [-l LOG] [-m] [-rl] [-r] [-rs RESTART_SUFFIX] [-p POTENTIAL] [-s] [-sf] [-e] [-nj] [--seed SEED] [-cm] [-t] [-cn CHECKPOINT_NAME] [input]

Fitting utility for (graph) atomic cluster expansion potentials.

positional arguments:
  input                 input YAML file, default: input.yaml

options:
  -h, --help            show this help message and exit
  -l LOG, --log LOG     log filename, default: log.txt
  -m, --multigpu        Single host/multi GPU distributed fit
  -rl, --restart-latest
                        Restart from latest checkpoint (use separately from -r/-rs)
  -r, --restart-best-test
                        Restart from latest best test checkpoint (use separately from -rs/-rl)
  -rs RESTART_SUFFIX, --restart-suffix RESTART_SUFFIX
                        Suffix of checkpoint to restart from, i.e. .epoch_10 (use separately from -r/-rl)
  -p POTENTIAL, --potential POTENTIAL
                        Potential configuration to load, model.yaml file
  -s, --save-model      Export model as TF saved model
  -sf, --save--fs       Export FS model as yaml to be loaded in CPP
  -e, --eager           Eager graph execution
  -nj, --no-jit         No JIT
  --seed SEED           Random seed (will overwrite value from input.yaml)
  -cm, --check-model    Check model consistency, without performing fit
  -t, --template        Generate a template 'input.yaml' file by dialog
  -cn CHECKPOINT_NAME, --checkpoint-name CHECKPOINT_NAME
                        Explicit name of the checkpoint (omit .index suffix)
```

--------------------------------

### Export Model to GRACE-FS/C++ Format using grace_utils

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/utilities.md

Exports a GRACE model to the GRACE-FS/C++ format (.yaml) using the grace_utils command. This requires the model YAML, checkpoint index, an output filename, and the `-sf` flag to specify the GRACE-FS format.

```bash
grace_utils -p /path/to/model.yaml -c /path/to/checkpoint/checkpoint.index export -n my_GRACE-FS.yaml -sf
```

--------------------------------

### LAMMPS Pair Style for GRACE

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/tutorials.md

Configures the LAMMPS simulation to use the GRACE potential. It specifies the `pair_style` as `grace` with `pad_verbose` for detailed output and `pair_coeff` to load the SavedModel and element information.

```lammps
pair_style grace pad_verbose
pair_coeff * * ../1-fit/seed/1/saved_model/ Al
```

--------------------------------

### Restarting GRACE Model Training

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Restarts a previously interrupted or completed GRACE model fitting process. It can automatically detect the best checkpoint or be pointed to specific model and checkpoint files.

```bash
gracemaker -r
```

```bash
gracemaker -r -p /path/to/model.yaml -cn /path/to/chekpoint.index
```

--------------------------------

### Process Fit Dictionary

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Calls the 'process_fit_dict' function with the 'fit_dict' and the defined 'fkey'. The 'align_folder' parameter is set to True. This function likely processes the fit data, potentially aligning it by folder, and returns a common prefix, a DataFrame, and a grouped DataFrame.

```python
common_prefix,df, gdf=process_fit_dict(fit_dict, fkey=fkey, align_folder=True)
```

--------------------------------

### Import Pandas Library

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Imports the pandas library, which is essential for data manipulation and analysis, providing data structures like DataFrames.

```python
import pandas as pd
```

--------------------------------

### grace_collect CLI

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/utilities.md

Utility to collect VASP calculation data from a top-level directory and store it in a *.pkl.gz file. This file can be used for fitting with gracemaker or pacemaker. It supports specifying reference energies per element or extracting them automatically from single-atom calculations.

```APIDOC
grace_collect [-h] [-wd WORKING_DIR] [--output-dataset-filename OUTPUT_DATASET_FILENAME] [--free-atom-energy [FREE_ATOM_ENERGY ...]] [--selection SELECTION]

Options:
  -h, --help            show this help message and exit
  -wd WORKING_DIR, --working-dir WORKING_DIR
                        top directory where keep calculations
  --output-dataset-filename OUTPUT_DATASET_FILENAME
                        pickle filename, default is collected.pckl.gzip
  --free-atom-energy [FREE_ATOM_ENERGY ...]
                        dictionary of reference energies (auto for extraction from dataset), i.e. `Al:-0.123 Cu:-0.456 Zn:auto`, default is zero. If option is `auto`, then it will be extracted from dataset
  --selection SELECTION
                        Option to select from multiple configurations of single VASP calculation: first, last, all, first_and_last (default: last)
```

--------------------------------

### Configure TPCalculator with Padding and Min Distance

Source: https://github.com/icams/grace-tensorpotential/blob/master/docs/gracemaker/quickstart.md

Configures the TPCalculator with advanced options like padding fraction, number of padded neighbors, and a minimum allowed bond distance. The `min_dist` parameter helps prevent non-physical short distances during relaxation.

```python
calc = TPCalculator('path/to/saved_model',
                     pad_neighbors_fraction = 0.05,
                     pad_atoms_number = 2,
                     min_dist=0.5)
```

--------------------------------

### Enable Inline Plotting

Source: https://github.com/icams/grace-tensorpotential/blob/master/examples/grace/visualize_metrics.ipynb

Enables inline plotting for IPython/Jupyter environments using Matplotlib, ensuring plots are displayed directly within the notebook or console.

```python
%pylab inline
```