MLPotential Keywords
********************


Engine MLPotential
==================

"Backend"
   Type:
      Multiple Choice

   Options:
      [FAIRChem, M3GNet, MACE, NequIP, TorchANI]

   Description:
      The machine learning potential backend.

"Device"
   Type:
      Multiple Choice

   Default value:
   Options:
      [, cpu, cuda:0, cuda:1]

   Description:
      Device on which to run the calculation (e.g. cpu, cuda:0).

      If empty, the device can be controlled using environment
      variables for TensorFlow or PyTorch.

"FAIRChem"
   Type:
      Block

   Recurring:
      False

   Description:
      Options for the FAIRChem machine learning potential backend.

   "ModelTask"
      Type:
         String

      Default value:
      Description:
         Model task to use if a custom UMA/eSEN model is supplied via
         a parameter file (e.g. 'OC20', 'OC22', 'OC25', 'ODAC',
         'OMat', 'OMC', 'OMol'). Ignored if a specific FAIRChem model
         is selected.

"MACE"
   Type:
      Block

   Recurring:
      False

   Description:
      Options for the MACE machine learning potential backend.

   "DataType"
      Type:
         Multiple Choice

      Default value:
         float32

      Options:
         [float32, float64]

      Description:
         Using "float32" is faster but less accurate, and generally
         recommended for MD. Conversely using "float64" is slower but
         more accurate, and recommended for geometry optimization.

   "EnableCuEquivariance"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Enable CUDA-accelerated cuEquivariance library for
         equivariant neural networks, if CUDA available.

   "ModelHead"
      Type:
         String

      Default value:
      Description:
         Model head to use if a custom MACE model is supplied via a
         parameter file (e.g. 'omat_pbe', 'omol', 'spice_wB97M',
         'ωB97M-D3(BJ)', 'rgd1_b3lyp', 'oc20_usemppbe',
         'matpes_r2scan'). Ignored if a specific MACE model is
         selected.

"MLDistanceUnit"
   Type:
      Multiple Choice

   Default value:
      Auto

   Options:
      [Auto, angstrom, bohr]

   GUI name:
      Internal distance unit

   Description:
      Unit of distances expected by the ML backend (not the ASE
      calculator). The ASE calculator may require this information.

"MLEnergyUnit"
   Type:
      Multiple Choice

   Default value:
      Auto

   Options:
      [Auto, Hartree, eV, kcal/mol, kJ/mol]

   GUI name:
      Internal energy unit

   Description:
      Unit of energy output by the ML backend (not the unit output by
      the ASE calculator). The ASE calculator may require this
      information.

"Model"
   Type:
      Multiple Choice

   Default value:
      ANI-2x

   Options:
      [Custom, AIMNet2-B973c, AIMNet2-wB97MD3, ANI-1ccx, ANI-1x, ANI-
      2x, eSEN-S-Con-OMol, M3GNet-UP-2022, MACE-MP-0-Large, MACE-
      MP-0-Medium, MACE-MP-0-Small, MACE-MPA-0, UMA-S-1.2-OC20,
      UMA-S-1.2-OC22, UMA-S-1.2-OC25, UMA-S-1.2-ODAC, UMA-S-1.2-OMat,
      UMA-S-1.2-OMC, UMA-S-1.2-OMol]

   Description:
      Select a pre-parameterized or custom model.

      AIMNet2-(wB97MD3/B973c): best for fast calculations of small,
      drug-like molecules; limited to aperiodic systems of 14 elements
      (H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I).

      ANI-(1x/1ccx/2x): best for very fast calculations of organic
      molecules; limited to elements H, C, N, O (ANI-1x/1ccx), F, S,
      Cl (ANI-2x).

      eSEN-S-Con-OMol: best for highly accurate calculations of
      diverse organic and bio-relevant molecules; not intended for
      calculations on periodic inorganic bulk materials.

      M3GNet-UP-2022: best for fast calculations of inorganic
      crystalline materials; not designed for accurately modeling
      small organic molecules or biomolecules.

      MACE-MP-0-(Small/Medium/Large): best for accurate periodic
      calculations of inorganic materials; size trades speed/accuracy;
      not designed for accurately modeling small organic molecules or
      biomolecules. MACE-MPA-0 has improved accuracy vs MP-0.

      UMA-S-1.2 variants: best for high accuracy calculations on a
      broad range of systems; choose from OC20 (adsorption and surface
      chemistry), OC22 (oxide catalysis), OC25 (electrocatalysis),
      ODAC (adsorption in porous frameworks), OMat (inorganic
      materials), OMC (organic molecular crystals), OMol (molecules,
      biomolecules, metal complexes, electrolytes); can be
      computationally expensive compared to other, more targeted
      models.

      Set Custom to choose a backend and provide your own parameters.

"NumThreads"
   Type:
      String

   Default value:
   GUI name:
      Number of threads

   Description:
      Number of threads.

      If not empty, OMP_NUM_THREADS will be set to this number; for
      PyTorch-engines, torch.set_num_threads() will be called.

"ParameterDir"
   Type:
      String

   Default value:
   GUI name:
      Parameter directory

   Description:
      Path to a set of parameters for the backend, if it expects to
      read from a directory.

"ParameterFile"
   Type:
      String

   Default value:
   Description:
      Path to a set of parameters for the backend, if it expects to
      read from a file.

"UnpairedElectrons"
   Type:
      Integer

   Default value:
      0

   Value Range:
      value >= 0

   GUI name:
      Spin polarization

   Description:
      The number of unpaired electrons in the system for a spin
      unrestricted calculation. The spin multiplicity is taken as this
      value plus one.

"Unrestricted"
   Type:
      Bool

   Default value:
      No

   Description:
      Enables spin unrestricted calculations, passing spin information
      to the machine learning model. Only applicable to
      'UMA-S-1.2-OMol', 'eSEN-S-Con-OMol' and custom FAIRChem models.
