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 validated against the workflow configuration contract.

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 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

    # Optional orbital hyperfine contribution handling [Optional]
    orbital_contribution: off # Ignore orbital hyperfine contribution
                          on  # Include orbital hyperfine contribution when available

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

    # Define paramagnetic centre [Required for pdip and when relaxation is enabled]
    paramagnetic_centre: [0.0, 0.0, 0.0] # Three Cartesian coordinates [x, y, z] in the same frame/units as the structure or HFC input

    # 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 QC-derived hyperfine data 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. For pdip, hyperfine:paramagnetic_centre must also be provided explicitly as three Cartesian coordinates [x, y, z].

The availability of individual hyperfine contributions depends on the selected method and backend support. If orbital_contribution is set to on, the hyperfine QC file must provide the required orbital data and a compatible DFT g tensor needed to evaluate the orbital shift contribution. This pathway applies only to QC-derived hyperfine routes for which these quantities are available. At present, this pathway is implemented only for ORCA 5 and ORCA 6 outputs.

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

    # Experimental spectrum reference in ppm [Optional]
    exp_reference: 0.56

Note

Experimental peak files are required for susceptibility fitting workflows.

For prediction workflows that enable relaxation, experiment files may also supply the temperature and magnetic field metadata used for relaxation when these values are not explicitly overridden in the relaxation block.

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.

Note

An experimental spectrum reference (exp_reference) may be provided to define an absolute chemical shift reference (in ppm) for experimental spectrum files. The reference peak is recognised within a tolerance of ±1 ppm.

If exp_reference is specified, spectrum_files must also be provided. Supplying exp_reference without experimental spectrum data is not supported and will result in a configuration error.

If omitted or set to null, no experimental spectrum referencing is applied.

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)

  # Optional workflow-level overrides for relaxation conditions
  temperature: 298.15 # Optional override; otherwise taken from experiment metadata
  magnetic_field_tesla: 11.75 # Optional override; otherwise taken from experiment metadata

  #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. When relaxation is enabled, hyperfine:paramagnetic_centre must also be provided.

Relaxation evaluation also requires temperature and magnetic field values. These may be provided explicitly as relaxation:temperature and relaxation:magnetic_field_tesla. If these overrides are omitted, the workflow falls back to the temperature and magnetic field read from the corresponding experiment:files inputs. Experimental metadata should therefore be set correctly for each experiment whenever workflow-level overrides are not used.

Prediction-only blocks#

Note

In prediction workflows, list-valued inputs 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 [Optional]
    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

    # Temperature to extract (K) [Required]
    temperature: [298.00]

Note

Susceptibility data are selected based on exact matching of the specified temperature. The temperature is compared numerically and must match the value provided in the input configuration.

Note

The format field is optional. If omitted, the susceptibility backend and (for ORCA outputs) the most advanced available method are selected automatically from the input file (e.g. NEVPT2 preferred over CASSCF).

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 # One of: fixed | permute | hungarian

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

    # Hungarian search policy [Optional, Hungarian only]
    search:
      mode: custom   # One of: fast | balanced | robust | custom
      n_attempts: 10      # Optional, mode: custom only
      max_iter: 100       # Optional, mode: custom only
      r2_threshold: 0.99  # Optional, mode: custom only

The three supported strategies are:

fixed

Uses the signal-to-nucleus assignments provided directly in the experimental data files. No reordering is performed.

permute

Exhaustively enumerates all permutations of assignments within the user-defined groups and selects the permutation that maximises the adjusted R². Guarantees the global optimum within the specified groups but scales factorially with group size.

hungarian

Uses the Hungarian algorithm (Munkres linear sum assignment) inside an iterative fit-and-reassign procedure. At each iteration the susceptibility tensor is fitted to the current assignment, shifts are predicted, and the Hungarian algorithm reassigns signals to nuclei so as to minimise the total absolute shift deviation. This is repeated until the assignment converges or the configured iteration limit is reached.

Search behaviour is controlled by the search mapping:

  • mode: fast uses n_attempts=1, max_iter=20, r2_threshold=0.95.

  • mode: balanced uses n_attempts=10, max_iter=100, r2_threshold=0.99.

  • mode: robust uses n_attempts=25, max_iter=250, r2_threshold=0.995.

  • mode: custom allows these three numeric controls to be provided explicitly under assignment:search.

If the search block is omitted, the policy layer resolves the default behaviour to the balanced mode.

This method scales polynomially with the number of signals and is therefore preferred over permute for large or heavily degenerate assignment problems.

Note

Assignment handling is applied only during susceptibility fitting.

For permute, the groups key must be explicitly defined.

For hungarian, the groups key is not supported. Hungarian assignment is controlled only through the optional search mapping.

The canonical Hungarian forms are search: {mode: balanced} for preset behaviour and search: {mode: custom, n_attempts: ..., max_iter: ..., r2_threshold: ...} for fully explicit search control.

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

    # Optional input units for the susceptibility fit variables
    # Default: A3
    # Supported: A3, cm3 mol-1, reduced
    input_units: reduced

    # 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.

Note

susc_fit:input_units: reduced uses the Curie-normalised convention already. Each susceptibility component is interpreted as chi_reduced = chi * T / Curie_prefactor(S) and is converted internally to

Å^3 units for the actual fit. Dimensionless parameters such as

rho_over_ax are not rescaled.

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.