CLI Reference#

Direct Upsampling toolkit CLI.

usage: dups [-h] [-v] [-q]
            {write-folders,read-folders,sample,ti,effqh,fes,thermo} ...

Positional Arguments#

command: Possible choices: write-folders, read-folders, sample, ti, effqh, fes, thermo

Named Arguments#

-v, --verbose

Print debug messages.

Default: False

-q, --quiet

Suppress info messages.

Default: False

Sub-commands#

write-folders#

Write a folder structure from a Direct Upsampling snapshot database. Produces {output_dir}/{volume}Ang3_{temperature}K/seed{N}_step{M}/. Without –calc only a structure file is written per snapshot; with –calc an ASE FileIOCalculator writes its full input set.

dups write-folders [-h] [--config FILE] [--calc NAME] [--params FILE]
                   [--set KEY=VALUE [KEY=VALUE ...]] [--format FMT]
                   [-j [FILE]] [--short]
                   [db_file] [output_dir]

Positional Arguments#

db_file: ASE database (.db) file with snapshots.
output_dir: Root output directory (default: snapshots).

Named Arguments#

--config: TOML config file. CLI args override values from the file.
--calc: ASE FileIOCalculator to use (e.g. vasp, emt). Use module:Class for non-standard names (e.g. lammpsrun:LAMMPS). Omit to write structure files only.
--params: File for calculator parameters. Can be .json (JSON object), .toml (TOML table), or VASP INCAR-style ‘KEY = VALUE’ file. –set values override keys from this file.
--set: Calculator parameters (e.g. –set ENCUT=400 prec=Accurate). Can be repeated: –set A=1 –set B=2. Overrides values from –params.
--format: ASE format for the structure file when –calc is not used. Defaults to vasp (POSCAR). Examples: extxyz, xyz, cif, lammps-data.
-j, --joblist: Write the list of created directories to FILE (default: jobList).
--short: Write one joblist entry per (V,T) grid point instead of per snapshot.

read-folders#

Read a Direct Upsampling folder structure produced by write-folders and write the resulting snapshots to an ASE database file.

dups read-folders [-h] [--config FILE] [input_dir] [db_file]

Positional Arguments#

input_dir: Root directory of the folder structure to read.
db_file: Output ASE database file (default: snapshots.db).

Named Arguments#

--config: TOML config file. CLI args override values from the file.

sample#

Run MD snapshot sampling on a (volume, temperature) grid using an ASE calculator. Writes sampled snapshots to an ASE database file. For custom calculators (MTP, etc.) use the Python API directly.

dups sample [-h] [--config FILE] [--calc NAME] [--params FILE]
            [--set KEY=VALUE [KEY=VALUE ...]] [--volumes V [V ...] |
            --volume-linspace START STOP N] [--temperatures T [T ...] |
            --temperature-linspace START STOP N] [--snapshots N]
            [--repeat N [N ...]] [--setting FILE]
            [atoms_file] [output_db]

Positional Arguments#

atoms_file: Structure file readable by ASE (POSCAR, extxyz, cif, …).
output_db: Output ASE database file (default: snapshots.db).

Named Arguments#

--config: TOML config file. CLI args override values from the file.
--calc: ASE calculator name (e.g. vasp, emt). Use module:Class for non-standard names (e.g. lammpsrun:LAMMPS).
--params: Calculator parameters file (.json, .toml, or VASP INCAR-style).
--set: Calculator parameters, e.g. –set ENCUT=400. Overrides –params.
--volumes: Explicit list of volumes (Å³/atom).
--volume-linspace: Volumes as a linspace: START STOP N.
--temperatures: Explicit list of temperatures in K.
--temperature-linspace: Temperatures as a linspace: START STOP N.
--snapshots: Snapshots per grid point (default: 150).
--repeat: Supercell repeat: one value (cubic) or three (NX NY NZ).
--setting: SamplingSetting as .json or .toml (e.g. thermostat_setting, log_md).

ti#

Run and analyse thermodynamic integration calculations.

dups ti [-h] {extract} ...

Positional Arguments#

ti_command: Possible choices: extract

Sub-commands#

extract#

Load a snapshot database produced by a thermodynamic integration run, integrate <ΔE> over lambda at each (volume, temperature) point, and write the resulting free energy differences to a CSV file.

dups ti extract [-h] [--config FILE] [--output FILE] [db_file]

Positional Arguments#

db_file: ASE snapshot database file (default: ti_snapshots.db).

Named Arguments#

--config: TOML config file. CLI args override values from the file.
--output: Output CSV file for free energy differences (default: ti_results.csv).

effqh#

Fit and manipulate effective quasi-harmonic (EffQH) models.

dups effqh [-h] {fit,change-reference,change-size} ...

Positional Arguments#

effqh_command: Possible choices: fit, change-reference, change-size

Sub-commands#

fit#

Fit an effective quasi-harmonic model to MD snapshots. Reads snapshots from an ASE database, fits force constants at each volume using hiphive, then fits a polynomial over volume. Writes the resulting ForceConstantFit to an HDF5 file.

dups effqh fit [-h] [--config FILE] [--output FILE] [--cutoffs Å [Å ...]]
               [--fit-order N] [--method METHOD]
               [atoms_file] [db_file]

Positional Arguments#

atoms_file: Reference structure file readable by ASE (POSCAR, extxyz, cif, …).
db_file: ASE snapshot database file (default: snapshots.db).

Named Arguments#

--config

TOML config file. CLI args override values from the file.

--output

Output HDF5 file for the ForceConstantFit (default: effqh.fcfit).

--cutoffs

Force constant cutoff radii in Å, one per order (default: [5.0]). A single value gives 2nd-order only; two values add 3rd-order, etc.

--fit-order

Polynomial order for interpolation over volume (default: auto).

--method

Possible choices: least-squares, lasso

Fitting method: least-squares or lasso (default: least-squares, or lasso for underdetermined systems).

change-reference#

Load an existing ForceConstantFit and refit it for a new reference structure. The new structure must have the same symmetry as the original but can differ in number of atoms or cell shape.

dups effqh change-reference [-h] [--atoms-file FILE] [--config FILE]
                            [--output FILE]
                            new_atoms_file [fc_fit_file]

Positional Arguments#

new_atoms_file: New reference structure to refit for.
fc_fit_file: Input ForceConstantFit HDF5 file (default: effqh.fcfit).

Named Arguments#

--atoms-file: Original reference structure used when fitting. Only needed for fcfit files that pre-date atoms storage (before 2026-05-06).
--config: TOML config file. CLI args override values from the file.
--output: Output HDF5 file for the refitted ForceConstantFit (default: effqh_new.fcfit).

change-size#

Load an existing ForceConstantFit and refit it for a new reference structure. The new structure must have the same symmetry as the original but can differ in number of atoms or cell shape.

dups effqh change-size [-h] [--atoms-file FILE] [--config FILE]
                       [--output FILE]
                       new_atoms_file [fc_fit_file]

Positional Arguments#

new_atoms_file: New reference structure to refit for.
fc_fit_file: Input ForceConstantFit HDF5 file (default: effqh.fcfit).

Named Arguments#

--atoms-file: Original reference structure used when fitting. Only needed for fcfit files that pre-date atoms storage (before 2026-05-06).
--config: TOML config file. CLI args override values from the file.
--output: Output HDF5 file for the refitted ForceConstantFit (default: effqh_new.fcfit).

fes#

Fit and inspect free energy surface contributions.

dups fes [-h] {combine,fit,eval} ...

Positional Arguments#

fes_command: Possible choices: combine, fit, eval

Sub-commands#

combine#

Load one or more .fes, .fcfit, or legacy EOS files, merge all their contributions into a single FreeEnergySurface, and write the result as a .fes JSON file.

dups fes combine [-h] [--config FILE] [--output FILE] FILE [FILE ...]

Positional Arguments#

FILE: .fes, .fcfit, or legacy EOS files to combine.

Named Arguments#

--config: TOML config file. CLI args override values from the file.
--output: Output .fes file (default: ‘combined.fes’).

fit#

Read one or more CSV files containing (volume, temperature, free energy) data, sum their contributions, fit a FreeEnergyContrib surface, and write the result as a .fes file. Each CSV must have index columns ‘volume’ and ‘temperature’ and a ‘free energy’ column. An ‘error’ column is used for combined error if present.

dups fes fit [-h] [--config FILE] [--name NAME] [--kind KIND] [--output FILE]
             CSV [CSV ...]

Positional Arguments#

CSV: One or more free-energy-difference CSV files to combine and fit.

Named Arguments#

--config

TOML config file. CLI args override values from the file.

--name

Name for the contribution (default: ‘ah’).

--kind

Possible choices: poly, fah, fvib, fel

Fit function type: [‘poly’, ‘fah’, ‘fvib’, ‘fel’] (default: ‘fah’).

--output

Output .fes file (default: ‘fah.fes’).

eval#

Load one or more .fes files, assemble a FreeEnergySurface, and evaluate a thermodynamic property at specified conditions. Conditions can be given as CLI flags (single point) or as a CSV file (one row per point), in which case the result is written as a new column in the output CSV.

dups fes eval [-h] [--property PROPERTY] [-v Å³] [-t K] [-p P]
              [--pressure-unit UNIT] [--conditions CSV] [--output FILE]
              [FILE ...]

Positional Arguments#

FILE: .fes or EOS files to assemble into the FreeEnergySurface.

Named Arguments#

--property

Possible choices: free-energy, pressure, volume, gibbs-energy

Property to evaluate: [‘free-energy’, ‘pressure’, ‘volume’, ‘gibbs-energy’] (default: ‘free-energy’).

-v, --volume

Volume in Å³ (required for free-energy and pressure).

-t, --temperature

Temperature in K.

-p, --pressure

Pressure (required for volume and gibbs-energy).

--pressure-unit

Possible choices: GPa, eV_per_Angstrom3

Pressure unit (default: ‘GPa’).

--conditions

CSV file with one row per evaluation point. Required columns depend on –property: ‘volume’+’temperature’ for free-energy/pressure, ‘pressure’+’temperature’ for volume/gibbs-energy.

--output

Output CSV file when –conditions is given (default: print to stdout).

thermo#

Assemble a FreeEnergySurface from the supplied files and compute thermodynamic properties as a function of temperature at a fixed pressure. Input files may be .fes (JSON) files, .fcfit (hdf5), or the old format text files (e.g. EVinet, Fqh, Fah).

dups thermo [-h] [--config FILE] [--tmax K] [--pressure GPa] [--output FILE]
            [--print PROPERTY CSV_FILE]
            [FILE ...]

Positional Arguments#

FILE: .fes or EOS files to assemble into the FreeEnergySurface.

Named Arguments#

--config: TOML config file. CLI args override values from the file.
--tmax: Maximum temperature in K (default: 1000).
--pressure: Pressure in GPa (default: 0.0).
--output: Output CSV file (default: ‘thermo.csv’).
--print: Exclusive mode: print two columns (temperature and PROPERTY) from CSV_FILE.

CLI Reference

Contents

CLI Reference#

Positional Arguments#

Named Arguments#

Sub-commands#

write-folders#

Positional Arguments#

Named Arguments#

read-folders#

Positional Arguments#

Named Arguments#

sample#

Positional Arguments#

Named Arguments#

ti#

Positional Arguments#

Sub-commands#

extract#

Positional Arguments#

Named Arguments#

effqh#

Positional Arguments#

Sub-commands#

fit#

Positional Arguments#

Named Arguments#

change-reference#

Positional Arguments#

Named Arguments#

change-size#

Positional Arguments#

Named Arguments#

fes#

Positional Arguments#

Sub-commands#

combine#

Positional Arguments#

Named Arguments#

fit#

Positional Arguments#

Named Arguments#

eval#

Positional Arguments#

Named Arguments#

thermo#

Positional Arguments#

Named Arguments#