Input YAML Files#

The input file is a declarative description of a calculation. Each top-level block maps to a specific subsystem (hyperfine source, susceptibility source, experiment, assignment, and fitting model). Values are used exactly as supplied.

Important Conventions

  1. The file must be valid YAML.

  2. Paths may be absolute or relative to the working directory.

  3. File patterns may contain the * wildcard.

  4. Unknown keys are not allowed and will result in a configuration error.

  5. YAML comment lines (#) are ignored.

User Responsibilities

You are responsible for ensuring that:

  • Coordinate frames are consistent across inputs (structure, hyperfine tensors, susceptibility tensors). If different programs are used, you must ensure that the workflow produces compatible frames.

  • Temperatures used for prediction or fitting correspond to the experiment you intend to model.

  • Units are interpreted correctly.

Configuration Blocks

Configuration blocks are grouped by their applicability to different workflow types.

  • General blocks may be used in any workflow.

  • Prediction-only blocks are used exclusively for pNMR prediction.

  • Fitting-only blocks are used exclusively for susceptibility fitting workflows.

The order of blocks in the YAML file is not significant. Blocks are presented here in a recommended logical order.

Note

This page documents input blocks for pNMR prediction and magnetic susceptibility fitting workflows. Additional or experimental workflows may be reorganised or removed and are not described here.

General blocks#

Blocks applicable to multiple workflow types.

Project#

Controls the output directory.

Applicability: Used as the output root for workflows that produce files.

# Project block schema (reference):
project:
    # Output directory name [Required]
    name: folder_name # Created if it does not exist

Note

The directory specified here is created automatically if it does not exist. All output files generated by the workflow are written under this directory.

Hyperfine#

Defines how hyperfine coupling (HFC) tensors are obtained.

Applicability: Used in workflows that require hyperfine tensor information, including: - pNMR prediction - Susceptibility fitting - Hyperfine analysis and export workflows

# Hyperfine block schema (reference):
hyperfine:
    # HFC Input Method Selection [Required]
    method: dft # QC-derived hyperfine tensors (Gaussian .log / ORCA .out)
            pdip # Dipolar hyperfine tensors via the point-dipole approximation from an .xyz structure
            csv # User-supplied hyperfine tensors from a .csv file

    # Filename [Required]
    file: hfc/file # Input file corresponding to the selected method

    # Define whether HFC averaging is needed [Optional]
    average: ['Me1', 'Me2'] # Chemical labels over which hyperfine tensors are averaged

    # Define pdip centre [Required for pdip method only]
    pdip_centres: ['Dy1'] # Atomic label(s) of the paramagnetic centre (including indexing)

    # Define Quantum Numbers [Required for csv and pdip methods only]
    spin: 2.5 # Spin quantum number S
    orbit: 5 # Orbital angular momentum L
    total_momentum_J: 7.5 # Total angular momentum J = L + S

Note

Hyperfine and magnetic susceptibility tensors are assumed to be expressed in compatible coordinate frames.

Automatic rotation of hyperfine tensors into the susceptibility eigenframe is performed only for specific combinations of susceptibility source and hyperfine method (e.g. QC-derived hyperfine tensors with ORCA-based susceptibility data).

Note

The interpretation of the hyperfine tensors depends on the selected method. For pdip and csv methods, explicit spin and angular momentum quantum numbers must be provided.

No validation is currently performed to ensure consistency between the supplied tensors and the molecular structure.

Chemical Labels#

Defines a mapping between atomic labels and chemical groups used for averaging, selection, and assignment operations.

Applicability:

Used in workflows that group nuclei by chemical labels.

# chem_labels block schema (reference):
chem_labels:
    # Chemical label mapping file [Required]
    file: chem_labels.csv # CSV file mapping atom labels to chemical groups

Note

Chemical labels are used to group nuclei for averaging and assignment purposes. This block is optional for pNMR prediction, but is mandatory for susceptibility fitting.

Nuclei#

Defines which nuclei are included in prediction or fitting workflows, either explicitly or via chemical group labels.

Applicability: Optional. Used in workflows that require explicit nucleus selection, including: - pNMR prediction - Susceptibility fitting

# nuclei block schema (reference):
nuclei:
    # Explicit nucleus selection [Required unless include_groups is provided]
    include: [H, C, H1] # Atom symbols and/or explicit atom labels

    # Selection via chemical labels [Optional]
    include_groups: [Me1, Me2] # Chemical labels defined in chem_labels

Note

Nuclei may be selected either explicitly using include or indirectly via chemical labels using include_groups.

If include_groups is provided, explicit nucleus selection is optional.

Experiment#

Defines the experimental shift or PCS data used as a target for susceptibility fitting.

Applicability: Used in fitting workflows that require experimental shift data.

# experiment block schema (reference):
experiment:
    # Experimental peak files [Required for fitting workflows]
    files: exp_*.csv # Experimental peak CSV files

    # Experimental spectrum files [Optional]
    spectrum_files: spectrum_*.csv

Note

Experimental peak files are required for susceptibility fitting workflows.

Spectrum files are auxiliary inputs and may only be used when corresponding experimental peak files are also provided. Supplying spectrum files without experimental peak data is not supported.

Diamagnetic Shifts#

Defines the source of diamagnetic shift data used to account for the diamagnetic contribution to observed NMR shifts.

Applicability: Optional. Used when diamagnetic shift data are provided explicitly.

# Diamagnetic schema (reference):
diamagnetic:
  method: dft # DFT-derived diamagnetic shifts for the molecular system
          csv # User-supplied diamagnetic shifts in CSV format
  file: dia.csv # Input file corresponding to the selected method

Note

This block specifies the diamagnetic shift data associated with the molecular system under study.

Diamagnetic Reference#

Defines a solvent-based diamagnetic reference used to calibrate diamagnetic shift values.

Applicability: Required when diamagnetic.method is set to dft.

# Diamagnetic schema (reference):
diamagnetic_ref:
  method: dft # DFT-derived diamagnetic reference shifts (e.g. solvent reference)
          csv # User-supplied diamagnetic reference shifts in CSV format
  file: dia_ref.csv # Reference file corresponding to the selected method

Note

The diamagnetic reference represents the solvent or reference environment used to calibrate diamagnetic shifts.

When DFT-derived diamagnetic shifts are used, the reference must be computed at the same level of theory (e.g. identical functional and basis set).

Relaxation Enhancement#

Defines optional relaxation models used to weight or broaden predicted shifts.

Applicability: Optional. Used in workflows that include relaxation-based shift broadening or weighting.

# relaxation block schema (reference):
relaxation:
  # Relaxation model [Optional]
  model: sbm # Solomon–Bloembergen–Morgan relaxation
    curie # Curie spin relaxation
    sbm curie # Combined SBM + Curie relaxation
    curie sbm # Equivalent to 'sbm curie' (ordering is ignored)

  # Coordinates of paramagnetic centre
  electron_coords: [0.0, 0.0, 0.0] # Required parameter

  # Magnetic field strength in Tesla
  magnetic_field_tesla: 9.4 # Required parameter

  # Temperature
  temperature: 300.0

  #Relaxation Parameters
  T1e: 0.2e-12 # Required parameter
  T2e: 0.2e-12 # Required parameter
  tR: 140e-12 # Required parameter

Note

Relaxation models modify the weighting or broadening of predicted shifts but do not alter the underlying susceptibility or hyperfine tensors.

When a relaxation model is specified, all required relaxation parameters must be provided. Temperature-dependent relaxation models (e.g. Curie-type terms) require an explicit temperature, while other models may not.

Prediction-only blocks#

Note

In prediction workflows, inputs provided as lists (e.g. susceptibility tensors, experimental data, or spectrum files) are processed positionally. The order of files must therefore be consistent across inputs, and matching is not performed automatically based on temperature or metadata.

Blocks used exclusively for pNMR prediction workflows.

Magnetic Susceptibility#

Defines the magnetic susceptibility tensor(s) used for pNMR prediction.

Applicability: Used in workflows involving pNMR prediction.

# susceptibility block schema (reference):
susceptibility:
    # Susceptibility tensor source file [Required]
    file: chi/orca.out # file containing magnetic susceptibility data

    # File format identifier [Required]
    format: orca_nev # NEVPT2-derived susceptibility data from ORCA output
            orca_cas # CASSCF-derived susceptibility data from ORCA output
            csv # User-supplied susceptibility tensor data in CSV format

    # Temperatures to extract (K) [Required]
    temperatures: [100, 200, 300]

Note

Susceptibility data are selected based on exact matching of the specified temperatures. Temperatures are compared numerically and must match the values provided in the input configuration.

Fitting-only blocks#

Blocks used exclusively for susceptibility fitting workflows.

Assignment#

Defines how experimental signals are mapped to nuclei during susceptibility fitting.

Applicability: Used in susceptibility fitting workflows that require assignment handling.

# assignment block schema (reference):
assignment:
    # Assignment strategy [Required]
    method: fixed # Use assignments explicitly provided in the experimental data
            permute # Permute assignments within user-defined groups

    # Permutation groups [Required for permute]
    groups:
      - [H1, H2, H3]
      - [H4, H5]

Note

Assignment handling is applied only during susceptibility fitting. For permutation-based strategies, all permutation groups must be explicitly defined by the user.

Assignment handling assumes that experimental data and assignments are ordered consistently by the user.

Magnetic Susceptibility Fitting#

Defines the susceptibility tensor model and fitting variables used to reproduce experimental shift data.

Applicability: Used in susceptibility fitting workflows.

# susc_fit block schema (reference):
susc_fit:
    # Susceptibility model type [Required]
    type: isoaxrho # Isotropic + axial + rhombic susceptibility model
          split # Split axial/rhombic susceptibility model
          full # Full anisotropic susceptibility tensor
          eigen # Eigenvalue-based susceptibility model
          isoeigen # Isotropic susceptibility in the eigenframe

    # Fit variables definition [Required for type: isoaxrho]
    variables:
      iso: [fit, 0.2]
      ax:  [fit, 0.1]
      rho_over_ax: [fix, 0.0]

    # Fit variables definition [Required for type: split]
    variables:
      iso: [fix, 0.0]
      dxx: [fit, 0.1]
      dxy: [fit, 0.1]
      dxz: [fit, 0.1]
      dyy: [fit, 0.1]
      dyz: [fit, 0.1]

    # Fit variables definition [Required for type: full]
    variables:
      dxx: [fit, 0.1]
      dyy: [fit, 0.1]
      dzz: [fit, 0.1]
      dxy: [fix, 0.0]
      dxz: [fix, 0.0]
      dyz: [fit, 0.1]

    # Fit variables definition [Required for type: eigen]
    variables:
      x: [fit, 0.00]
      y: [fit, 0.01]
      z: [fix, 0.02]

    # Fit variables definition [Required for type: eigen]
    variables:
      dxx: [fit, 0.02]
      dxy: [fit, 0.01]
      iso: [fix, 0.00]

    average_shifts: 'all' # Average shifts over all chemical labels
                    ["Me1", "Me2"] # Average shifts over the specified chemical labels

Note

The required fit variables depend on the selected susceptibility model type. No automatic consistency checks are performed between the chosen model and the provided variable definitions.

Temperature Dependence of Magnetic Susceptibility Fitting#

Defines temperature-dependent susceptibility fitting models, including optional treatment of temperature-independent paramagnetism (TIP).

Applicability: Optional. Used in susceptibility fitting workflows that model temperature dependence.

# susc_vt block schema (reference)
susc_vt:
    # Fitting strategy [Required]
    method: vt_2nd_order # Second-order temperature-dependent susceptibility fitting
            ht_limit # High-temperature limit susceptibility fitting

    # Temperature Independent Paramagnetism extracture strategy: [Optional]
    tip_type: fit # Fit temperature-independent paramagnetism (TIP) parameters
              fix_tip_from_ab_initio # Fix TIP values from ab initio calculations

    # Choose file consisting TIP data [Required for tip_type fix_tip_from_ab_initio]
    ab_initio_file: susc/nevpt2.out

    # Choose level of theory needed for reading TIP data [Required for tip_type: fix_tip_from_ab_initio]
    ab_initio_format: orca_nev

    # Fit variables definition [Required for method vt_2nd_order]
    variables:
      # Susceptibility variable blocks
      iso:
        intercept: [fit, 0.0] # Required parameter
        slope: [fit, 0.0] # Required parameter
        tip: [fix, -0.00112] # Required when tip_type is set to fit
      ax:
        intercept: [fit, 0.0] # Required parameter
        slope: [fit, 0.0] # Required parameter
        tip: [fix, 0.0010] # Required when tip_type is set to fit
      rho:
        intercept: [fit, 0.0] # Required parameter
        slope: [fit, 0.0] # Required parameter
        tip: [fix, 0.0] # Required when tip_type is set to fit

Note

Temperature-dependent fitting extends the base susceptibility fitting model. When TIP parameters are fixed from ab initio data, the corresponding file and format must be provided explicitly.

Notes on optional command-line controls

Note

Command-line options may override plotting and output behaviour but do not modify the configuration semantics defined by the YAML file.