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

The file must be valid YAML.
Paths may be absolute or relative to the working directory.
File patterns may contain the * wildcard.
Unknown keys are not allowed and will result in a configuration error.
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

The hyperfine structure and the susceptibility must share a coordinate frame. The pseudocontact shift couples the susceptibility tensor to each nucleus’s position, so a mismatch between the two frames silently produces wrong shifts and a misaligned PCS field.

CSV / tensor susceptibility (susceptibility: file: … with format: csv): there is no geometry to align against, so the tensor is used as-is and is assumed to already be expressed in the same frame as the hyperfine structure (hyperfine: file). You are responsible for ensuring this — no automatic alignment is performed.
Ab-initio susceptibility with DFT hyperfine (e.g. an ORCA susceptibility output combined with hyperfine: method: dft): the susceptibility-source geometry is automatically aligned onto the hyperfine geometry (Kabsch superposition) and the tensors are rotated into the shared frame. This requires the same molecule with the same number of atoms in the same order. Different atom counts are rejected outright, and if the post-alignment RMSD exceeds ~1 Å a prominent warning is emitted (the tensor orientation, and hence the pseudocontact shifts and PCS field, may be unreliable) — check that the two structures correspond.

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.

Note

Hyperfine CSV format (``method: csv``)

The CSV file must be in the canonical SimpNMR molecule CSV format — the same format produced by save_molecule_to_csv. Comment lines beginning with # are ignored.

Required columns:

atom_label () — atom label matching the structure (e.g. H1, C3)
x (Å), y (Å), z (Å) — Cartesian coordinates in Ångströms

Spin hyperfine columns (all seven must be present together):

A_fc_iso (ppm Å^-3) — isotropic Fermi-contact value, ⅓ Tr[A_FC]
A_sd_xx, A_sd_xy, A_sd_xz, A_sd_yy, A_sd_yz, A_sd_zz (all ppm Å^-3) — unique elements of the symmetric spin-dipole tensor A_SD

The full hyperfine tensor is reconstructed internally as A = A_SD + A_fc,iso · I.

Optional orbital hyperfine columns (all six must be present together):

A_orb_xx, A_orb_xy, A_orb_xz, A_orb_yy, A_orb_yz, A_orb_zz (all ppm Å^-3) — unique elements of the symmetric orbital hyperfine tensor

Optional label columns:

chem_label () — chemical/symmetry label for each atom
chem_math_label () — LaTeX-formatted label for plot annotations

Example header line:

atom_label (),chem_label (),x (Å),y (Å),z (Å),A_fc_iso (ppm Å^-3),A_sd_xx (ppm Å^-3),A_sd_xy (ppm Å^-3),A_sd_xz (ppm Å^-3),A_sd_yy (ppm Å^-3),A_sd_yz (ppm Å^-3),A_sd_zz (ppm Å^-3)

The easiest way to produce a valid file is to run a dft calculation first and save the result with save_molecule_to_csv; the output can then be edited or used directly as a csv input.

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.

Note

chem_labels CSV format

The CSV file must contain at minimum the columns atom_label and chem_label. Two additional columns are optional:

chem_math_label — a LaTeX-formatted label used in plot annotations (e.g. $tBu_1$ ). Falls back to chem_label if omitted.
isotope — NMR isotope string for the atom group (e.g. 1H, 13C). When absent or empty, the most abundant NMR-active isotope for the element is used automatically (H → 1H, C → 13C, N → 15N, etc.). Providing this column is only necessary when a non-default isotope is required (e.g. 2H for deuterium).

Example:

atom_label,chem_label,chem_math_label,isotope
H1,tBu1,$tBu_1$,1H
H2,tBu1,$tBu_1$,1H
C1,qC,$qC$,13C

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

Experiment CSV format (wide format)

Experimental peak data are stored in a wide-format CSV file. Temperature and magnetic field are specified as the first two header rows; one block of signal columns is written for each (T, B) condition, allowing multiple conditions to coexist in a single file:

temperature (K),298.15,298.15,298.15,305,305,305
magnetic field (T),4.7,4.7,4.7,4.7,4.7,4.7
assignment,shift (ppm),width (Hz),area (),assignment,shift (ppm),width (Hz),area ()
aax,82.89,587.31,4108.48,...
py5,24.14,97.24,5139.30,...

Required columns (repeated for each condition block):

assignment — unique label for each signal (non-empty, unique per isotope)
shift (ppm) — observed chemical shift in ppm
width (Hz) — linewidth (FWHM) in Hz
area — integrated signal area

Optional columns:

r1 (Hz) — longitudinal relaxation rate R₁ in s⁻¹
L/G — Lorentzian-to-Gaussian lineshape ratio (default 1.0)
isotope — nuclear isotope tag (e.g. 1H, 13C). When present, each signal is attributed only to plots and filters for that isotope. When absent, isotope attribution falls back to the chem_labels file or a single-isotope shortcut if only one isotope is present.

Every signal must carry a non-empty assignment. Assignments must be unique within each isotope in a given (T, B) block.

A trailing comma at the end of the temperature or magnetic field header row (as produced by some spreadsheet applications) is ignored automatically.

Legacy format

Files beginning with # temperature and # magnetic_field comment lines (one file per condition) are still accepted for backwards compatibility.

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 the reference compound used to convert absolute DFT shieldings into chemical shifts via δ^dia = σ_ref − σ.

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

Three modes are available:

Option 1 — explicit values per isotope (recommended)

Provide the averaged reference shielding for each isotope directly. No extra file is needed — just look up σ_ref from your DFT output once and hardcode it. This is unambiguous when predicting multiple isotopes (1H and 13C simultaneously).

diamagnetic_ref:
  method: values
  values:
    1H: 31.74       # avg σ(H) in TMS at your DFT level
    13C: 188.07     # avg σ(C) in TMS at your DFT level

Option 2 — single reference file (all isotopes)

A single DFT or CSV file is averaged per element and mapped to isotopes automatically (H → 1H, C → 13C, etc. via the default isotope table). Suitable when all predicted isotopes share the same reference compound and file.

diamagnetic_ref:
  method: dft   # or csv
  file: tms_shielding.log

Option 3 — per-isotope reference files

Supply a separate reference file for each isotope. Useful when different isotopes use different reference compounds or levels of theory.

diamagnetic_ref:
  method: dft
  file:
    1H:  tms_1h.log
    13C: tms_13c.log

Note

The reference shielding and the diamagnetic shielding (diamagnetic:file) must be computed at the same level of theory (functional and basis set).

Why per-isotope references matter: a DFT NMR calculation on a diamagnetic analogue produces shieldings for all atoms simultaneously (1H, 13C, etc.). Each isotope requires its own reference shielding (e.g. TMS gives both σ_ref(1H) and σ_ref(13C), which are numerically very different). Using a single-file reference with method: dft maps these correctly via element → isotope conversion. Use method: values when you want to be explicit or when the automatic mapping is not sufficient.

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

  # Rotational correlation time τ_R: give EITHER an explicit tR ...
  tR: 140e-12 # τ_R in seconds (required unless τ_R is estimated below)

  # ... OR have τ_R estimated from the molecular shape and solvent viscosity
  tau_r_method: ellipsoid   # Optional: 'ellipsoid' (Perrin) or 'beadshell'
  tau_r_solvent: CDCl3      # Solvent name from the built-in viscosity database
  tau_r_eta: 5.4e-4         # Optional: explicit viscosity (Pa·s); overrides tau_r_solvent
  tau_r_shell: 0.0          # Optional: solvent shell thickness added to vdW radii (Å)
  tau_r_sigma: 0.6          # Optional: minibead radius (Å) for the bead-shell model

  min_linewidth_hz: 5.0 # Optional minimum linewidth floor (Hz); added to the
                        # calculated R2/π linewidth before converting to ppm

Note

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

min_linewidth_hz sets a floor on the predicted linewidth. The value (in Hz) is added to the SBM/Curie-calculated R₂/π linewidth before conversion to ppm, accounting for contributions such as field inhomogeneity or natural linewidth that are not captured by the relaxation model. Defaults to 0.0 (no floor).

When a relaxation model is specified, all required relaxation parameters must be provided. When relaxation is enabled, hyperfine:paramagnetic_centre must also be provided.

The rotational correlation time τ_R may be given explicitly as tR (in seconds) or estimated from the molecular geometry and solvent viscosity by setting tau_r_method (ellipsoid or beadshell) together with either tau_r_solvent (a name from the built-in solvent database) or tau_r_eta (an explicit viscosity in Pa·s). When tau_r_method is set, tR is not required. The estimation uses the relaxation:temperature (or the experiment temperature) for the viscosity lookup.

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 unless method: spin_only]
    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(s) to extract or compute (K) [Required]
    temperatures: [298.00]

    # Susceptibility source method [Optional]
    method: spin_only # Compute isotropic χ from quantum numbers via the Curie law;
                      # no susceptibility file is needed (see note below)

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

Note

Spin-only susceptibility (``method: spin_only``)

When method: spin_only is set, no susceptibility file is required. The isotropic susceptibility χ_iso is computed analytically at each requested temperature via the Curie law:

\[\chi_\text{iso} = \frac{\mu_0 \mu_B^2 g_\text{eff}^2 S_\text{eff}(S_\text{eff}+1)}{3 k_B T}\]

where the effective g-factor g_eff is the Landé g-factor computed from the quantum numbers S, L, and J provided in the hyperfine block, and S_eff = J for lanthanides (J defined) or S for transition metals (L = 0). The resulting susceptibility tensor is isotropic (diagonal, all components equal to χ_iso).

Because the tensor is isotropic, only the Fermi contact shift contributes (isotropic A_iso × χ_iso); the pseudocontact contribution (which requires tensor anisotropy) is identically zero. This mode is therefore only meaningful when a QC-derived hyperfine file with non-zero A_iso is provided (e.g. hyperfine:method: dft). Using hyperfine:method: pdip with method: spin_only will produce zero paramagnetic shifts and a warning is emitted.

The spin quantum number S must be supplied in the hyperfine block. L and J are optional:

If J is omitted (or null), g = g_e ≈ 2.0023 and S_eff = S (pure spin Curie law). Appropriate for transition metals with quenched orbital angular momentum or organic radicals.
If S, L, and J are all provided, the Landé g_J factor is used and S_eff = J. Appropriate for lanthanides.

# Transition metal (spin-only, L quenched):
hyperfine:
    method: dft
    file: hfc/molecule.out
    spin: 2.5           # S — required

susceptibility:
    method: spin_only
    temperatures: [298.00]

# Lanthanide (Landé g_J, S_eff = J):
hyperfine:
    method: dft
    file: hfc/molecule.out
    spin: 2.5           # S
    orbit: 5            # L
    total_momentum_J: 7.5  # J

susceptibility:
    method: spin_only
    temperatures: [298.00, 310.00]

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
      rmse_threshold: 0.5   # Optional, mode: custom only (ppm)

    # Cost-matrix weighting terms [Optional, Hungarian only]
    area_weight: 0.0    # Weight for signal area vs. group-size consistency
    width_weight: 0.0   # Weight for linewidth vs. 1/r^6 consistency
    r1_weight: 0.0      # Weight for R1 vs. 1/r^6 consistency

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, rmse_threshold=0.0 (early stopping disabled).
mode: balanced uses n_attempts=10, max_iter=100, rmse_threshold=0.0 (early stopping disabled).
mode: robust uses n_attempts=200, max_iter=500, rmse_threshold=0.0 (early stopping disabled).
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.

The cost matrix used by the Hungarian algorithm can be augmented with additional physically motivated terms via the following optional keys:

area_weight: Adds a term based on the consistency between the normalised experimental signal area and the normalised group size (number of equivalent nuclei sharing the same chemical label). Both quantities are normalised to sum to 1 across all signals/labels before comparison. This steers the algorithm to match signals with large integrated areas to labels with many equivalent nuclei. Default: 0.0 (disabled).
width_weight: Adds a term based on the consistency between the normalised experimental linewidth and the normalised mean 1/r⁶ for each label, where r is the distance from each nucleus to the paramagnetic centre. Since paramagnetic relaxation scales as 1/r⁶, signals with larger linewidths are steered toward labels closer to the metal. Both quantities are normalised to sum to 1. Requires hyperfine.paramagnetic_centre to be set. Default: 0.0 (disabled).
r1_weight: Analogous to width_weight but uses experimental R1 values instead of linewidths. Signals without R1 data are treated as zero. Default: 0.0 (disabled).

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 through the optional search mapping and the optional cost-matrix weighting keys (area_weight, width_weight, r1_weight).

The canonical Hungarian forms are search: {mode: balanced} for preset behaviour and search: {mode: custom, n_attempts: ..., max_iter: ..., rmse_threshold: ...} for fully explicit search control. All weighting terms default to 0.0 and can be combined freely.

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: isoaxrh # 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: isoaxrh]
    variables:
      iso: [fit, 0.2]
      ax:  [fit, 0.1]
      rh_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

    # Output figure toggles [Optional]. Any omitted key defaults to true.
    figures:
      fitted_shifts: true
      shift_components: true
      spectra: true
      r6_fit: true
      tau_space: true
      bubble_plots: false
      chi_t: false

    # Fitted-shifts / mean-components figure layout [Optional]
    shifts_format: narrow      # size variant: standard | narrow | vertical | vertical_extended (default: standard)
    shifts_width_scale: 1.3    # multiply the figure width only (default: 1.0)
    shifts_labels: false       # draw per-point labels on the fitted-shifts scatter (default: true)

    # Broken x-axis for the predicted/experimental spectrum figure [Optional].
    spectra_break:
      # Choose ONE way to place the break(s):
      #  (a) break just after a named peak, or at an explicit ppm:
      after_label: tBu4a       # or:  after_ppm: -7.5
      #  (b) explicit per-panel ppm limits, high->low ppm (overrides after_*):
      segments:
        - [14, -3]
        - [-13, -43]
        - [-70, -76]
      scales: [1, 4, 20]       # per-panel vertical magnification (shown as "xN" labels)
      width_ratios: [2, 1, 0.5] # relative panel widths (overrides equal_width)
      equal_width: true        # equal panel widths (used only when width_ratios is absent)
      label_scale: 0.7         # scale factor for peak-label font size

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 rh_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
      rh:
        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.

Relaxation Fit Options#

Controls the r^-6 distance-model fits for R1 and linewidth that are run automatically as part of the susceptibility fitting workflow.

Applicability: Optional. Used in susceptibility fitting workflows when R1 or linewidth data are present in the experiment files.

# fit_relaxation block schema (reference):
fit_relaxation:
    # Fixed τe for Fermi-contact subtraction; also the reference value used
    # when selecting the derived τe root (see note below) [Optional]
    tau_e: 5.0e-13  # s — T1e = T2e used to subtract contact contribution

    # τe axis range for τ-space plots; also bounds the derived-τe search [Optional]
    tau_e_range: [1.0e-14, 1.0e-11]  # [min, max] in s

    # τR axis range for τ-space plots [Optional]
    tau_r_range: [1.0e-10, 1.0e-7]   # [min, max] in s

    # Known rotational correlation time to overlay on τ-space plots [Optional]
    tau_r_fixed: 1.5e-9  # s

    # Distance-weighting exponent for the r⁻⁶ fit [Optional]
    # Each point is weighted by r_eff**distance_power (0 = equal weights).
    distance_power: 0.0

    # Automatic τR calculation from structure (Optional)
    # Requires tau_r_method plus either tau_r_solvent or tau_r_eta.
    tau_r_method: ellipsoid       # "ellipsoid" (default) or "beadshell"
    tau_r_solvent: D2O            # solvent name for viscosity lookup
    # tau_r_eta: 1.1e-3           # explicit viscosity (Pa·s); overrides tau_r_solvent
    # tau_r_shell: 0.0            # solvation shell thickness added to vdW radii (Å)
    # tau_r_sigma: 0.6            # minibead radius for bead-shell model (Å)

Note

Contact contribution subtraction

Observed R1 and linewidth contain both the distance-dependent dipolar/Curie contribution and a distance-independent Fermi-contact contribution. Only the dipolar/Curie part scales as r⁻⁶; fitting without removing the contact part biases the slope p1.

When tau_e is provided, the SBM contact relaxation rate is computed for each chem_label group using the isotropic hyperfine coupling A_iso from the loaded hyperfine tensors and subtracted before the r⁻⁶ fit. For linewidth the contact R2 (s^-1) is converted to ppm via R2 / (π |γI| B0).

The contact-subtracted observable, the raw observable, and the per-signal contact contribution are all written to the output CSV.

If tau_e is omitted (default) no subtraction is performed and the fit is identical to the previous behaviour. The p2 intercept term then absorbs both diamagnetic and contact baseline contributions.

Note

Fitting algorithm

The r⁻⁶ model $p_1 r^{-6} + p_2$ is fitted using Huber regression (epsilon = 1.35). Residuals smaller than 1.35 σ are treated as inliers with an ordinary least-squares (L2) penalty; larger residuals are down-weighted with an L1 penalty. This makes the fit resistant to outliers — for example a mis-assigned nucleus or an unusually flexible side-chain close to the metal — while leaving well-behaved points unaffected.

Note

R1 / R2 decomposition

When a rotational correlation time τR is available (from tau_r_method or tau_r_fixed) together with at least one r⁻⁶ relaxation fit, an electronic correlation time τe is derived by inverting the fitted p1. A single molecular τe is used: when several r⁻⁶ fits are available (linewidth and/or R1, across isotopes) the most trustworthy one is chosen automatically from the number of data points and the relative uncertainty of p1. Because the SBM p1 is non-monotonic in τc the inversion can have two roots; the root closest to tau_e (default 1 ps) within tau_e_range is selected.

The resulting (τR, τe) are then used to compute the full R₁ and R₂ decomposition (SBM dipolar/contact + Curie) for every nucleus, written to peak_data_<TEMPERATURE>_K_<FIELD>_T.csv and recorded in that file’s header. In this case the spectrum linewidths are taken from this relaxation model rather than the raw r⁻⁶ linewidth fit.

Parameter uncertainties are estimated by bootstrap (1000 resamples with replacement) and reported as p1_err / p2_err in the output CSV and annotation boxes.

Note

Overlaying a known τ:sub:`R` on τ-space plots

When tau_r_fixed is provided, each τ-space heatmap plot receives an additional overlay:

A dashed horizontal line drawn at the specified τ_R value.
A dotted vertical line and a cross marker at every intersection of that horizontal with the central contour (p₁^calc = p₁^fit), indicating the τ_e value consistent with the fitted slope at the given τ_R.
A bottom-left annotation reporting both τ_R and the derived τ_e.

The grid is automatically extended to include tau_r_fixed even if it falls outside the tau_r_range window, so the heatmap colours are always shown across the full displayed region.

This is useful when τ_R has been determined independently (e.g. from NMR diffusion measurements or molecular dynamics) and you want to read off the implied τ_e directly from the plot.

Note

Automatic τ:sub:`R` calculation from molecular structure

Setting tau_r_method enables automatic per-temperature τ_R computation from the molecular coordinates that are already loaded by the pipeline (the same structure used for the hyperfine tensor calculation). The result is used as tau_r_fixed for each individual τ-space plot — overriding any manually specified tau_r_fixed value.

tau_r_method must be accompanied by either tau_r_solvent (for automatic Arrhenius-corrected viscosity) or tau_r_eta (for a fixed user-supplied viscosity):

fit_relaxation:
    tau_r_method: ellipsoid
    tau_r_solvent: D2O         # viscosity corrected per temperature

Alternatively, supply the viscosity explicitly (useful for non-standard solvents or when the Arrhenius correction is not desired):

fit_relaxation:
    tau_r_method: ellipsoid
    tau_r_eta: 1.1e-3          # Pa·s, applied at every temperature

Models

ellipsoid: The molecule is approximated by a triaxial ellipsoid; the Perrin analytical rotational diffusion tensor is computed from the three principal semi-axes. Fast and appropriate for compact molecules.
beadshell: The molecular surface is covered with minibeads (radius tau_r_sigma, default 0.6 Å) and the rotational diffusion tensor is obtained from the Rotne–Prager–Yamakawa hydrodynamic interaction matrix. More accurate for non-ellipsoidal or highly elongated structures.

Solvation shell

Both models can include a solvation shell of thickness tau_r_shell (Å, default 0.0) added uniformly to all van der Waals radii before computing the molecular shape.

Standalone tool

τ_R values can also be calculated independently, outside a fit_susc run, using the simpnmr calc_tau_c command (see Standalone CLI utilities).

Note

τ-space heatmap axis ranges

tau_e_range and tau_r_range set the axis limits of the 2D τ-space heatmap that maps which (τe, τR) pairs are consistent with the fitted p1 within the 95 % confidence interval. If omitted, default ranges are used. Values must be positive and ordered [min, max].

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.