Command Line Interface
Tadah!MLIP’s CLI follows one simple pattern; once you know the conventions you can drive every tool—from dataset wrangling to hyper-parameter optimisation.
Basic invocation
tadah <command> [<subcommand>] [OPTIONS]
command – one of the top-level verbs listed in the map below (
analysis,data…).subcommand – some commands are families that expose specialist sub-tools, e.g.
analysis bfuncordata dedup. Commands without children omit this level.OPTIONS – long keys start with
--; single-letter aliases start with-. Boolean switches are always written in CAPS for their short form (-F,-S,-A…).
Tasks vs. direct CLI
Anything that can be written on the command line can be placed inside a
task file and executed with --task tasks.tadah.
A task file is simply the CLI translated into an INI-style block:
# global options
NUMERIC 14
VERBOSE 2
TASK predict
DBFILE data.tadah
FORCE true
ANALYTICS true
...
Short-hand rules
Boolean flags never take a value on the CLI:
--force✓--force true✗Lists accept space-separated tokens or comma/range syntax (
1,3-5,10-20:2).Mutually exclusive options are flagged in the help (
Excludes); Tadah!MLIP aborts if you combine them.Any multi-value option can be repeated:
--dbfile file1 file2or--dbfile file1 --dbfile file2.
Top-level command map
|
Visualise basis / cutoff functions or compute descriptors
|
|
Create & manipulate datasets
|
|
Detailed help for any command/option (dot-notation) |
|
Global hyper-parameter optimisation of a model |
|
Run a trained potential on datasets or raw structures |
|
Evaluate benchmark properties
|
|
Fit a new potential ( |
Commands reference
analysis
DESCRIPTION:
Visual analysis commands.
LONG DESCRIPTION:
Visual analysis commands (e.g., descriptor, bfunc, cutoff).
OPTIONS:
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis descriptor -d dataset.tadah -p pot.tadah -o out.txt
analysis bfunc
DESCRIPTION:
Evaluate and plot basis functions.
LONG DESCRIPTION:
Long description: Evaluate and plot basis functions.
OPTIONS:
--type <string> [<string> ...]
Basis function type. "2b Y" or "mb N".
Number of arguments: Min 1, Max 2
Description:
Choice of basis function. For example: "2b Y" or "mb N".
Where Y/N controls computation of the cutoff function.
Examples:
- string1 string2
- string1 /path/to/file
--rescale
Rescale the basis function by the cutoff function. This is useful for visualisation purposes.
Default: false
--outfile, -o <string>
String value.
Number of arguments: Min 1, Max 1
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- validString
- /path/to/file
--range, -r <START> <STOP> <NPOINTS>
Plotting range [start stop npoints].
Number of arguments: Min 3, Max 3
Examples:
- 0.1 9.5 100
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--derivative
Calculate derivative of the function.
Default: false
--index, -i <index>[,<index>...]
<start>-<stop>
<start>-<stop>:<step>
Index pattern.
Number of arguments: Min 1, Max MAX_INT
Description:
Allows flexible selection of dataset indices. Supports single indices, ranges
(e.g., start-stop), lists, or intervals (start-stop:step). Indices are 1-based.
Repeated indices are removed automatically.
Examples:
- 1,3,5
- 1-4,7,9
- 1-10:2
OPTIONS::input
Provide either a potential file, a configuration file, or a task file.
--potential, -p <file>
Trained model file.
Number of arguments: Min 1, Max 1
Needs: range, type
Excludes: task, config
Examples:
- pot.tadah
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Needs: range, type
Excludes: task, potential
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis bfunc -p pot.tadah -o bfunc.txt -r 0 5 500 --type 2b Y
analysis check_bounds
DESCRIPTION:
Validate HPO bounds: at every corner of the OPTIM box, run the pre-flight audit. Returns non-zero if any corner trips a FAIL finding. CI-friendly.
LONG DESCRIPTION:
Phase 7 of the HPO bound-validation pipeline. Reads the HPOTARGET file
referenced by the seed config, parses every OPTIM <KEY> (range) <lo> <hi>
line into a Bound, samples corners (full 2^k for k <= 12, otherwise a
Latin-hypercube subsample of min(2^k, ceil(k log2(k)))), and runs the
Phase 5 pre-flight audit (run_preflight_from_db) at each corner with
the corner's parameter values substituted into the seed Context.
Returns exit code 0 if all corners pass and 1 if any corner produces a
FAIL finding.
OPTIONS:
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--hpotarget <file>
HPO target file.
Number of arguments: Min 1, Max 1
Examples:
- hpotargets.txt
OPTIONS::input
Provide a training config and an HPOTARGET file.
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Excludes: task
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis check_bounds -c train.tadah --hpo-target config.hpo
analysis cutoff
DESCRIPTION:
Evaluate and plot cutoff functions.
LONG DESCRIPTION:
Long description: Evaluate and plot cutoff functions.
OPTIONS:
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--range, -r <START> <STOP> <NPOINTS>
Plotting range [start stop npoints].
Number of arguments: Min 3, Max 3
Examples:
- 0.1 9.5 100
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--derivative
Calculate derivative of the function.
Default: false
OPTIONS::input
Provide either a cutoff type or a task file.
--type <string> [<string> ...]
Generic types.
Number of arguments: Min 1, Max MAX_INT
Needs: range
Excludes: task
Examples:
- string1 string2
- string1 /path/to/file
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis cutoff -o cutoff.txt -r 0 3.14 100 -t "CutCos" --derivative
analysis dataset_stats
DESCRIPTION:
Compute dataset statistics (per-pair r_ij, neighbour counts, energy/force scales) for HPO bound validation.
LONG DESCRIPTION:
Computes per-element-pair distance percentiles + KDE peaks, neighbour-count
percentiles per element, energy-per-atom percentiles, force-norm percentiles,
and a material-class label over the supplied DBFILEs / STRUCTUREs. Writes
the result to a text file (default 'dataset_stats.tadah') consumed by
tadah hpo --suggest-bounds and the pre-flight design-matrix audit.
OPTIONS:
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
OPTIONS::input
Structure source or a task file. Select from the following options:
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Needs: outfile
Excludes: task, dbfile, structure
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile
Excludes: task, config
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--structure, -s <string> [<string> ...]
Unified structural input(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile
Excludes: task, config
Description:
Supported file formats: .cif (Crystallographic Information File), VASP
(POSCAR/CONTCAR), and CASTEP (.cell). The online option fetches structures
from databases (MP, COD, NOMAD). Multiple structures can be space-separated
or repeated. A mix of files and online sources is allowed.
Examples:
- crystal.cif
- crystal1.cif crystal2.cell
- mp-42 crystal.cif
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis dataset_stats -c train.tadah --outfile stats.tadah
analysis descriptor
DESCRIPTION:
Calculate structure descriptors.
LONG DESCRIPTION:
Calculate structure descriptors.
OPTIONS:
--potential, -p <file>
Trained model file.
Number of arguments: Min 1, Max 1
Examples:
- pot.tadah
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--index, -i <index>[,<index>...]
<start>-<stop>
<start>-<stop>:<step>
Index pattern.
Number of arguments: Min 1, Max MAX_INT
Description:
Allows flexible selection of dataset indices. Supports single indices, ranges
(e.g., start-stop), lists, or intervals (start-stop:step). Indices are 1-based.
Repeated indices are removed automatically.
Examples:
- 1,3,5
- 1-4,7,9
- 1-10:2
--force, -F
Include forces.
Default: false
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--merge
Merge deduplication results into one file.
Default: false
--append
Append to the existing file.
Needs: outfile
Default: false
OPTIONS::input
Structure source or a task file. Select from the following options:
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile, potential
Excludes: task
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--structure, -s <string> [<string> ...]
Unified structural input(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile, potential
Excludes: task, index
Description:
Supported file formats: .cif (Crystallographic Information File), VASP
(POSCAR/CONTCAR), and CASTEP (.cell). The online option fetches structures
from databases (MP, COD, NOMAD). Multiple structures can be space-separated
or repeated. A mix of files and online sources is allowed.
Examples:
- crystal.cif
- crystal1.cif crystal2.cell
- mp-42 crystal.cif
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis descriptor -d dataset.tadah -p pot.tadah -o out.txt --index 1,3,5
analysis suggest_bounds
DESCRIPTION:
Suggest data-driven OPTIM bounds for the configured descriptors.
LONG DESCRIPTION:
Reads the user's training config (DBFILEs + TYPE2B / TYPEMB), computes
dataset statistics (per-pair r_ij percentiles + KDE peaks), then walks
each configured descriptor's meta() and proposes one OPTIM bound per
parameter. Writes a compilable OPTIM block (or to stdout if --outfile
is omitted). Phase 4 of the HPO bound-validation pipeline.
OPTIONS:
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
OPTIONS::input
Source: a training config or a task file.
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Excludes: task
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah analysis suggest_bounds -c train.tadah --outfile suggested.hpo
data
DESCRIPTION:
Dataset management commands.
LONG DESCRIPTION:
Dataset management commands (convert, print, write, merge, split, dedup, sample, balance).
OPTIONS:
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data --task tasks.tadah
data balance
DESCRIPTION:
Apply energy shifts and/or rescaling to a dataset.
LONG DESCRIPTION:
Modify a dataset by applying element-specific energy shifts or rescaling
the weights for energies, forces, and stresses. The procedure can include
threshold checks, forcing near-zero values to a default weight, while large
magnitudes are inversely weighted. The updated dataset is then written to
one or more output files, which can be merged if desired. This approach
enhances the dataset's consistency and is especially useful when refining
potential parameters or emphasizing certain configurations during training.
OPTIONS:
--force, -F
Apply rescaling to forces.
Default: false
--stress, -S
Apply rescaling to stresses.
Default: false
--threshold <double> [<double> ...]
Floating point thresholds for energy, force, and stress.
Number of arguments: Min 1, Max 3
Default: 1e-4, 1e-5, 1e-6
Description:
If energy or the sum of force norms or the stress matrix norm exceeds the
corresponding threshold, the relevant quantity will be rescaled using an
inverse weighting..
Examples:
- 2.0 -4.65 0.4
- -1.0
--rescale
Rescale structure weights.
Default: false
Description:
Applies inverse weighting to energies, forces, and stresses based on their
magnitudes. Specifically:
• Energies: 1 / | energy |
• Total force: 1 / Σ‖ force_i ‖
• Stress: 1 / ‖stress‖
This ensures smaller magnitudes keep their weights, while large values are
downweighted to mitigate numerical instability.
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--eshift <double> [<double> ...]
Per-atom reference energy to subtract from each configuration.
Number of arguments: Min 1, Max MAX_INT
Description:
Per-element reference energies. If there are multiple species, the number of
values must match the number of species (sorted by Z). At load time the total
energy of each configuration is reduced by sum_Z N_Z * ESHIFT[Z], so an
isolated-atom config with energy E_atom and ESHIFT[Z]=E_atom yields a
post-shift energy of zero. Used by tadah train, tadah predict, tadah hpo,
and tadah data balance. Persisted into pot.tadah for prediction round-trip.
Examples:
- 0.5
- 0.5 -0.1
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--append
Append to the existing file.
Needs: outfile
Default: false
--merge
Merge deduplication results into one file.
Default: false
--index, -i <index>[,<index>...]
<start>-<stop>
<start>-<stop>:<step>
Index pattern.
Number of arguments: Min 1, Max MAX_INT
Description:
Allows flexible selection of dataset indices. Supports single indices, ranges
(e.g., start-stop), lists, or intervals (start-stop:step). Indices are 1-based.
Repeated indices are removed automatically.
Examples:
- 1,3,5
- 1-4,7,9
- 1-10:2
OPTIONS::input
Select from the following options:
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile
Excludes: task
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data balance -d db.tadah --rescale --eshift 0.5 --numeric 16 --outfile balanced.tadah
- tadah data balance -d db1.tadah db2.tadah --rescale --outfile balanced1.tadah balanced2.tadah
data convert
DESCRIPTION:
Convert DFT output file(s) to Tadah! dataset format.
LONG DESCRIPTION:
Convert DFT output file(s) to Tadah! dataset format.
OPTIONS:
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--append
Append to the existing file.
Needs: outfile
Default: false
OPTIONS::input
Input sources for printing. Select from the following options:
--dft-file <string> [<string> ...]
Input DFT file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile
Excludes: task
Description:
A single file or multiple files (space-separated). Used to extract reference
data for training. Supported formats: VASP (OUTCAR, vasprun.xml), CASTEP
(.castep, .md, .geom).
Examples:
- run1.outcar
- run1.outcar run2.outcar
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data convert --dft-file run1.outcar -o output.tadah
data dedup
DESCRIPTION:
Remove duplicate structures from a dataset.
LONG DESCRIPTION:
Remove duplicate structures from Tadah! dataset(s). The merge option combines output into single file.
OPTIONS:
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--threshold <double> [<double> ...]
Floating point comparison threshold.
Number of arguments: Min 1, Max MAX_INT
Examples:
- 1e-4
--merge
Merge deduplication results into one file.
Default: false
--append
Append to the existing file.
Needs: outfile
Default: false
OPTIONS::input
Select from the following options:
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile
Excludes: task
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data dedup -d db1.tadah db2.tadah -o dedup1.tadah dedup2.tadah
- tadah data dedup -d db1.tadah db2,tadah -o db_merged.tadah --merge
data merge
DESCRIPTION:
Merge multiple dataset files into a single file.
LONG DESCRIPTION:
Merge multiple dataset files into a single file.
OPTIONS:
--outfile, -o <string>
String value.
Number of arguments: Min 1, Max 1
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- validString
- /path/to/file
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
OPTIONS::input
Sources for merging. Select from the following options:
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data merge -d db1.tadah db2.tadah -o merged.tadah
data print
DESCRIPTION:
Print structure information to screen.
LONG DESCRIPTION:
Print structure(s) information from dataset or structure files.
OPTIONS:
--index, -i <index>[,<index>...]
<start>-<stop>
<start>-<stop>:<step>
Index pattern.
Number of arguments: Min 1, Max MAX_INT
Description:
Allows flexible selection of dataset indices. Supports single indices, ranges
(e.g., start-stop), lists, or intervals (start-stop:step). Indices are 1-based.
Repeated indices are removed automatically.
Examples:
- 1,3,5
- 1-4,7,9
- 1-10:2
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
OPTIONS::input
Input sources for printing. Select from the following options:
--dbfile, -d <string>
String value.
Number of arguments: Min 1, Max 1
Excludes: task
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- validString
- /path/to/file
--structure, -s <string> [<string> ...]
Unified structural input(s).
Number of arguments: Min 1, Max MAX_INT
Excludes: task, index
Description:
Supported file formats: .cif (Crystallographic Information File), VASP
(POSCAR/CONTCAR), and CASTEP (.cell). The online option fetches structures
from databases (MP, COD, NOMAD). Multiple structures can be space-separated
or repeated. A mix of files and online sources is allowed.
Examples:
- crystal.cif
- crystal1.cif crystal2.cell
- mp-42 crystal.cif
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data print -d dataset.tadah
- tadah data print -s crystal.cif
data sample
DESCRIPTION:
Sample configurations from a dataset.
LONG DESCRIPTION:
Sample a subset of configurations from an existing dataset to create a new,
single output dataset. For the --index option, ensure requested sample size
does not exceed the number of available configurations.
OPTIONS:
--outfile, -o <string>
String value.
Number of arguments: Min 1, Max 1
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- validString
- /path/to/file
--uniform <unsigned integer>
Sample uniformly every N-th entry.
Number of arguments: Min 1, Max 1
Excludes: random, index
Examples:
- 10
--random <unsigned integer>
Randomly sample N entries.
Number of arguments: Min 1, Max 1
Excludes: uniform, index
Examples:
- 5
--index, -i <index>[,<index>...]
<start>-<stop>
<start>-<stop>:<step>
Index pattern.
Number of arguments: Min 1, Max MAX_INT
Excludes: random, uniform
Description:
Allows flexible selection of dataset indices. Supports single indices, ranges
(e.g., start-stop), lists, or intervals (start-stop:step). Indices are 1-based.
Repeated indices are removed automatically.
Examples:
- 1,3,5
- 1-4,7,9
- 1-10:2
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--append
Append to the existing file.
Needs: outfile
Default: false
OPTIONS::input
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile
Excludes: task
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data sample -d full.tadah -o sample.tadah
data split
DESCRIPTION:
Split a dataset into parts.
LONG DESCRIPTION:
Split a dataset into parts.
OPTIONS:
--even
Split dataset into equal-size partitions. The number of partitions is determined by the number of output files provided. The last partition may be smaller if the dataset size is not divisible by the number of partitions.
Excludes: chunk, percent
Default: false
--chunk <unsigned integer> [<unsigned integer> ...]
Specify chunk sizes.
Number of arguments: Min 1, Max MAX_INT
Excludes: even, percent
Examples:
- 20 5 3
- 10
--percent <unsigned integer> [<unsigned integer> ...]
Specify percentage partition.
Number of arguments: Min 1, Max MAX_INT
Excludes: even, chunk
Examples:
- 20 5 3
- 10
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--shuffle
Randomize entries before splitting.
Default: false
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--append
Append to the existing file.
Needs: outfile
Default: false
OPTIONS::input
Select from the following options:
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data split -d db.tadah -o part1.tadah part2.tadah --even
data write
DESCRIPTION:
Write structures into a chosen format.
LONG DESCRIPTION:
Write structures from a dataset or a structure file or online source into a chosen format.
OPTIONS:
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--index, -i <index>[,<index>...]
<start>-<stop>
<start>-<stop>:<step>
Index pattern.
Number of arguments: Min 1, Max MAX_INT
Description:
Allows flexible selection of dataset indices. Supports single indices, ranges
(e.g., start-stop), lists, or intervals (start-stop:step). Indices are 1-based.
Repeated indices are removed automatically.
Examples:
- 1,3,5
- 1-4,7,9
- 1-10:2
--format, -f <fmt>
Output format (e.g., vasp, castep, lammps).
Number of arguments: Min 1, Max 1
Examples:
- castep
- lammps
- vasp
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
OPTIONS::input
Structure sources for writing. Select from the following options:
--dbfile, -d <string>
String value.
Number of arguments: Min 1, Max 1
Needs: outfile, index, format
Excludes: task
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- validString
- /path/to/file
--structure, -s <string> [<string> ...]
Unified structural input(s).
Number of arguments: Min 1, Max MAX_INT
Needs: outfile, format
Excludes: task, index
Description:
Supported file formats: .cif (Crystallographic Information File), VASP
(POSCAR/CONTCAR), and CASTEP (.cell). The online option fetches structures
from databases (MP, COD, NOMAD). Multiple structures can be space-separated
or repeated. A mix of files and online sources is allowed.
Examples:
- crystal.cif
- crystal1.cif crystal2.cell
- mp-42 crystal.cif
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah data write -d dataset.tadah -o output.cell -f cell -i 7
explain
DESCRIPTION:
Explain tadah command or option in more detail.
LONG DESCRIPTION:
This is a help command that provides detailed information about a specific command or option in the Tadah! software. It is useful for users who want to understand the purpose and usage of a particular command or option.
OPTIONS:
OPTION <command>
<command>.<option>
<command>.<subcommand>.<option>
Command or option to explain in a dot separated format.
Required: true
Number of arguments: Min 1, Max 1
Description:
The command or option to explain. The format is dot-separated, where each part represents a level of the command hierarchy. For example, to explain the 'verbose' option of the 'train' command, you would use 'train.verbose'.
Examples:
- tadah explain train.task
- tadah explain data.split.even
EXAMPLES:
- tadah explain task
- tadah explain train.verbose
- tadah explain data.split.even
hpo
DESCRIPTION:
Optimize the model architecture and hyperparameters.
LONG DESCRIPTION:
Refine your model's architecture and hyperparameters using Tadah!'s nested
fitting procedure, an iterative approach that goes beyond standard force-
and energy-focused methods. By evaluating trial potentials with LAMMPS
scripts, this framework allows you to incorporate performance constraints
such as surface energies or phase stability, significantly enhancing model
transferability. The global optimization algorithm systematically explores
the parameter space, producing a robust interatomic potential tailored to
your priorities for accuracy, speed, and other metrics. This flexible
workflow enables users to define search space constraints, assign weights
to different objectives, and tune performance for a wide range of
applications.
OPTIONS:
--force, -F
Include forces.
Default: false
--stress, -S
Include stresses.
Default: false
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--lscale <double>
Uniform length rescale factor applied to atomic positions, cell, and reference forces at load time.
Number of arguments: Min 1, Max 1
Default: 1.0
Description:
Multiplies atomic positions and cell vectors by this factor at the moment a
dataset is loaded for training, prediction, or HPO. Reference forces are
divided by the factor (chain rule on E(r)); stresses (stored as virial in
energy units) are invariant under uniform length rescaling. The chosen factor
is persisted into pot.tadah so future tadah predict and tadah hpo runs
apply the same transformation. Use --no-lscale at predict time to override.
LSCALE is a training-side concept: the LAMMPS pair_style does NOT re-apply
LSCALE. The user is expected to provide LAMMPS positions at the scale that
matches the trained model (e.g. experimental lattice).
Examples:
- 1.0030
--eshift <double> [<double> ...]
Per-atom reference energy to subtract from each configuration.
Number of arguments: Min 1, Max MAX_INT
Description:
Per-element reference energies. If there are multiple species, the number of
values must match the number of species (sorted by Z). At load time the total
energy of each configuration is reduced by sum_Z N_Z * ESHIFT[Z], so an
isolated-atom config with energy E_atom and ESHIFT[Z]=E_atom yields a
post-shift energy of zero. Used by tadah train, tadah predict, tadah hpo,
and tadah data balance. Persisted into pot.tadah for prediction round-trip.
Examples:
- 0.5
- 0.5 -0.1
--eshift-atom
Derive ESHIFT from isolated-atom configurations in the dataset (mean per Z).
Default: false
Description:
Scans the loaded dataset for single-atom configurations (natoms == 1), groups
them by atomic number, and sets ESHIFT[Z] to the mean per-Z energy. If a
species has no isolated-atom config in the dataset, ESHIFT[Z] = 0 for that
species and a WARNING is logged. If multiple isolated-atom configs of the same
Z disagree by more than 1e-3 eV, an INFO line records the spread.
Mutually exclusive with explicit ESHIFT and ESHIFT_DBATOM.
--eshift-dbatom
Derive ESHIFT by least-squares atomic-energy fit over the database.
Default: false
Description:
Fits per-element reference energies by least squares: minimise
||y - M beta||^2 where y[i] is the total energy of configuration i and
M[i, k] is the count of species k in configuration i. The fitted beta_k
becomes ESHIFT[Z(k)]. More robust than ESHIFT_ATOM when the dataset has no
isolated-atom configs but does have compositional diversity.
Mutually exclusive with explicit ESHIFT and ESHIFT_ATOM.
--efilter <E_min_per_atom> <E_max_per_atom>
Drop configurations whose per-atom energy is outside [E_min, E_max] (eV).
Number of arguments: Min 2, Max 2
Description:
Outlier filter applied at load time before any energy-shift derivation or
training-weight assignment, so outliers do not poison ESHIFT_ATOM /
ESHIFT_DBATOM / EWEIGHT_TEMP. The threshold is compared against E/N_atoms
(per-atom energy). Both bounds must be supplied. To disable, omit the key.
Examples:
- -12.0 -2.0
--ffilter <double>
Drop configurations where any atomic force magnitude exceeds this value (eV/Å).
Number of arguments: Min 1, Max 1
Description:
Outlier filter applied at load time. A configuration is dropped if any single
atom has ‖F‖ > FFILTER. Useful for catching unconverged SCF or otherwise
broken DFT runs.
Examples:
- 20.0
--wdbfile <double> [<double> ...]
Per-dataset weight multipliers, one per DBFILE entry.
Number of arguments: Min 1, Max MAX_INT
Description:
Multiplies eweight, fweight, and sweight of every configuration in the
corresponding DBFILE by the given factor. Use to bias training toward or away
from particular datasets. Composes multiplicatively with WDBFILE_AUTO.
Examples:
- 1.0 0.5 0.1
--wdbfile-auto <double>
Auto size-balance datasets: per-config weight multiplied by 1/N_i^alpha.
Number of arguments: Min 1, Max 1
Default: 0.0
Description:
Rebalances per-dataset contributions to the training loss by multiplying each
configuration's weight by N_i^(-alpha), where N_i is the number of (post-
filter) configurations in dataset i. alpha=0 disables (default). alpha=0.5
is the recommended starting point (sqrt-inverse, soft balance). alpha=1
fully equalises aggregate dataset contribution. Composes multiplicatively
with user-given WDBFILE.
Examples:
- 0.5
- 1.0
--eweight-temp <double>
Boltzmann reweighting temperature in Kelvin (multiplies eweight).
Number of arguments: Min 1, Max 1
Description:
After ESHIFT is applied, multiplies each configuration's eweight by
exp(-(E/N - E_min)/(kB * T)) where E_min is the minimum per-atom energy in
the dataset and kB = 8.617333262e-5 eV/K. Emphasises low-energy
configurations. Composes multiplicatively with the per-structure eweight
already in the dataset file. Omit the key to disable.
Examples:
- 300
- 1000
--zero-com-force
Subtract per-config mean force so each configuration has zero net force.
Default: false
Description:
Per configuration, subtracts the mean force from each atom so that the sum of
forces over the configuration is exactly zero. Standard DFT post-processing
trick to remove residual translational forces from incomplete relaxation/SCF.
OPTIONS::input
Input sources for hpo. Select from the following options:
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Needs: hpotarget
Excludes: task
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
--validation <string> [<string> ...]
Validation dataset file(s).
Number of arguments: Min 1, Max MAX_INT
Examples:
- valid.tadah
--hpotarget <file>
HPO target file.
Number of arguments: Min 1, Max 1
Examples:
- hpotargets.txt
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah hpo -c config.tadah --hpotarget hpotargets.txt --validation valid.tadah
predict
DESCRIPTION:
Predict properties using a trained model.
LONG DESCRIPTION:
Predict using an already trained model. Energy per atom is always calculated,
while forces and stresses are optional. By default, energies are written to
energy.pred, and if forces or stresses are calculated, they are written to
forces.pred and stress.pred, respectively. You can use a task file with a DBFILE
key to list prediction datasets or STRUCTURE to list files or online structures
(see tadah explain predict.structure for supported types). Alternatively, you
can provide Tadah! datasets or individual structure files or online sources via
the command line.
OPTIONS:
--analytics, -A
Perform analytics.
Excludes: structure
Default: false
--outfile, -o <energy_file> [<force_file>] [<stress_file>]
Output file name(s) for predicted values. The first file is for energies, followed by forces/stresses if requested. Specify filename for every requested output.
Number of arguments: Min 1, Max 3
Default: energy.pred, forces.pred, stress.pred
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--potential, -p <file>
Trained model file.
Number of arguments: Min 1, Max 1
Examples:
- pot.tadah
--force, -F
Include forces.
Default: false
--stress, -S
Include stresses.
Default: false
--error
Generate error estimates.
Default: false
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--lscale <double>
Uniform length rescale factor applied to atomic positions, cell, and reference forces at load time.
Number of arguments: Min 1, Max 1
Default: 1.0
Description:
Multiplies atomic positions and cell vectors by this factor at the moment a
dataset is loaded for training, prediction, or HPO. Reference forces are
divided by the factor (chain rule on E(r)); stresses (stored as virial in
energy units) are invariant under uniform length rescaling. The chosen factor
is persisted into pot.tadah so future tadah predict and tadah hpo runs
apply the same transformation. Use --no-lscale at predict time to override.
LSCALE is a training-side concept: the LAMMPS pair_style does NOT re-apply
LSCALE. The user is expected to provide LAMMPS positions at the scale that
matches the trained model (e.g. experimental lattice).
Examples:
- 1.0030
--eshift <double> [<double> ...]
Per-atom reference energy to subtract from each configuration.
Number of arguments: Min 1, Max MAX_INT
Description:
Per-element reference energies. If there are multiple species, the number of
values must match the number of species (sorted by Z). At load time the total
energy of each configuration is reduced by sum_Z N_Z * ESHIFT[Z], so an
isolated-atom config with energy E_atom and ESHIFT[Z]=E_atom yields a
post-shift energy of zero. Used by tadah train, tadah predict, tadah hpo,
and tadah data balance. Persisted into pot.tadah for prediction round-trip.
Examples:
- 0.5
- 0.5 -0.1
--efilter <E_min_per_atom> <E_max_per_atom>
Drop configurations whose per-atom energy is outside [E_min, E_max] (eV).
Number of arguments: Min 2, Max 2
Description:
Outlier filter applied at load time before any energy-shift derivation or
training-weight assignment, so outliers do not poison ESHIFT_ATOM /
ESHIFT_DBATOM / EWEIGHT_TEMP. The threshold is compared against E/N_atoms
(per-atom energy). Both bounds must be supplied. To disable, omit the key.
Examples:
- -12.0 -2.0
--ffilter <double>
Drop configurations where any atomic force magnitude exceeds this value (eV/Å).
Number of arguments: Min 1, Max 1
Description:
Outlier filter applied at load time. A configuration is dropped if any single
atom has ‖F‖ > FFILTER. Useful for catching unconverged SCF or otherwise
broken DFT runs.
Examples:
- 20.0
--zero-com-force
Subtract per-config mean force so each configuration has zero net force.
Default: false
Description:
Per configuration, subtracts the mean force from each atom so that the sum of
forces over the configuration is exactly zero. Standard DFT post-processing
trick to remove residual translational forces from incomplete relaxation/SCF.
--no-lscale
(predict) Ignore any LSCALE recorded in the loaded potential file.
Default: false
Description:
At predict time, override the LSCALE value stored in pot.tadah. Use when
the dataset you are predicting on is already at the trained-model scale.
--no-eshift
(predict) Ignore any ESHIFT recorded in the loaded potential file.
Default: false
Description:
At predict time, override the ESHIFT values stored in pot.tadah. Use when
the dataset you are predicting on is already at the shifted baseline (or you
just want raw model output without any reference energy subtraction).
OPTIONS::input
Input sources for prediction. Select from the following options:
--dbfile, -d <string> [<string> ...]
Path(s) to Tadah! database file(s).
Number of arguments: Min 1, Max MAX_INT
Needs: potential
Description:
Absolute or relative path to the Tadah! database file(s). The relative path
is interpreted relative to the current working directory. Multiple dataset
paths can be provided either as space-separated tokens or by repeating
this key.
Examples:
- dbfile /path/to/dbfile
- dbfile /path/to/dbfile1 /path/to/dbfile2
--structure, -s <string> [<string> ...]
Unified structural input(s).
Number of arguments: Min 1, Max MAX_INT
Needs: potential
Description:
Supported file formats: .cif (Crystallographic Information File), VASP
(POSCAR/CONTCAR), and CASTEP (.cell). The online option fetches structures
from databases (MP, COD, NOMAD). Multiple structures can be space-separated
or repeated. A mix of files and online sources is allowed.
Examples:
- crystal.cif
- crystal1.cif crystal2.cell
- mp-42 crystal.cif
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah predict -p pot.tadah -s crystal1.cif crystal2.cif --force
- tadah predict -p pot.tadah -d db1.tadah --numeric 12
- tadah predict -p pot.tadah -d db.tadah --stress --outfile predicted_energy.dat predicted_stresses.dat
properties
DESCRIPTION:
Evaluate physical properties for MLIP target evaluation.
LONG DESCRIPTION:
Evaluate physical properties for MLIP target evaluation (e.g., pairwise, ecurve, eos, defect, surface, mechanics).
OPTIONS:
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah properties pairwise -p pot.tadah -o out.txt -r 0 10 100 -a "Kr Kr"
properties pairwise
DESCRIPTION:
Compute E vs. r for a given potential.
OPTIONS:
--eshift <double>
Shift the energy curve by this value. If zero is provided the curve will be shifted by the furthest right value of the curve. Provide single double for --eshift if potential is either two- or many-body. If potential is both two- and many-body, provide three doubles for --eshift. The first double if for total energy second double is for two-body, the third for many-body.
Number of arguments: Min 1, Max 3
Description:
Per-element reference energies. If there are multiple species, the number of
values must match the number of species (sorted by Z). At load time the total
energy of each configuration is reduced by sum_Z N_Z * ESHIFT[Z], so an
isolated-atom config with energy E_atom and ESHIFT[Z]=E_atom yields a
post-shift energy of zero. Used by tadah train, tadah predict, tadah hpo,
and tadah data balance. Persisted into pot.tadah for prediction round-trip.
Examples:
- 2.0
- -1.0
--outfile, -o <string> [<string> ...]
Output file.
Number of arguments: Min 1, Max MAX_INT
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--range, -r <START> <STOP> <NPOINTS>
Plotting range [start stop npoints].
Number of arguments: Min 3, Max 3
Examples:
- 0.1 9.5 100
--atompair, -a <element1> <element2>
Pair of chemical elements.
Number of arguments: Min 1, Max 2
Examples:
- "Kr Kr"
--force, -F
Include forces.
Default: false
--numeric <unsigned integer>
Numeric output precision.
Number of arguments: Min 1, Max 1
Default: 12
Description:
Sets the number of decimal places for output.
Examples:
- 12
--error
Generate error estimates.
Default: false
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--bondenergy
Calculate bond energy instead of per atom value.
Default: false
OPTIONS::input
Select from the following options:
--potential, -p <file>
Trained model file.
Number of arguments: Min 1, Max 1
Needs: outfile, range, atompair
Excludes: task
Examples:
- pot.tadah
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah properties pairwise -p pot.tadah -o out.txt -r 0 10 100 -a "Kr Kr"
refit
DESCRIPTION:
Refit a tabulated EAM potential into a native Tadah model.
LONG DESCRIPTION:
Convert a tabulated EAM potential (setfl format: eam/alloy or eam/fs, single
element) into a native Tadah model: the pair, density and embedding functions
are re-fitted with flexible Tadah basis functions. The result can be used
directly or tuned further with tadah hpo.
Output files (default name, config key):
- pot.tadah (OUTFILE, -o): the fitted Tadah potential, for tadah predict,
LAMMPS pair_style tadah, and as the seed for tadah hpo.
- refit.eam (SETFL_OUT): setfl table rebuilt from the fitted functions, for
side-by-side comparison with the input potential in LAMMPS.
- refit.hpotarget (HPOFILEOUT, --hpofileout): ready-to-run tadah hpo target
file with search bounds around the fitted parameters.
- refit_opt.log (REFIT_LOG): live fit log, updated during the run.
- refit_curve_{phi,rho,F}.dat, refit_compare.dat, refit_range_report.dat:
diagnostics with fitted vs original curves, residuals, fit windows.
Config-file options (EAM is the only required key):
- EAM <file>: input setfl potential to refit (required).
- REFIT_MODE: compact (default; small optimised basis) | dense (fast
fixed grids).
- REFIT_BASIS: basis family. Knot5 (compact default) | Blip (dense
default) | Blip5 | Knot3 | KnotMix.
- REFIT_TOL_AMBIENT / REFIT_TOL_COMPRESSED: accuracy targets in meV/atom
near equilibrium / under compression (defaults 0.1 / 1.0).
- REFIT_REACH_SMIN: smallest compression a/a0 the fit must stay accurate
at (default 0.75).
- OPTIM_PCT: +-percent search bounds written to the hpotarget file
(default 5).
- OUTPUT_GRID_SCALE: output setfl grid density relative to the input
(default 1.0).
- Dense mode only: REFIT_LEVEL (coarse|balanced|fine|accurate), N2B,
NRHO_BASIS, NF_BASIS, REFIT_MAX_ESCALATIONS.
- Compact ladder: REFIT_COMPACT_NMAX, REFIT_COMPACT_STALL,
REFIT_COMPACT_SHARE, REFIT_COMPACT_OPT_EVERY, REFIT_COMPACT_INSERT_TOPK,
REFIT_COMPACT_SEED.
- Stage pipeline (compact mode): INIT -> EXPLORE -> REFINE -> FUSE, each its
own multi-line block. INIT (no optimisation) declares manual/anchored,
optionally PINned knots/blips. EXPLORE/REFINE/FUSE each take a nested
OPTIMIZER block (LIB/ALGO + stop criteria, same syntax as tadah hpo).
Omit any block to use its defaults (default EXPLORE = global MLSL + inner
SBPLX). See HPO_REFIT_2B_EAM/REDESIGN/configs for examples.
- Advanced: REFIT_PLACEMENT, REFIT_REACH_MARGIN, REFIT_R_LO_FRAC,
REFIT_CONSTRAIN_F0.
Two additional modes operate on EXISTING refit outputs instead of a
tabulated EAM file:
- --edit <pot.tadah>: add or remove one basis function of one curve
(--func {phi|rho|F} with --add <centre> or --remove <centre>). Adding
uses a zero coefficient, so the potential is unchanged until tadah hpo
varies the new dimension; removing compensates via the neighbouring
coefficients. Writes an edited potential and a regenerated hpotarget.
- --retarget <file.hpotarget>: rewrite the OPTIM search bounds of an
existing hpotarget (--pct global or KEY=N per-key percentages,
--set 'KEY(i)=lo,hi' absolute overrides, --in-place).
For knot-family potentials both modes keep RCUT2B/RCUTMB consistent with
the largest knot position (the true effective cutoff).
Run tadah explain refit.<key> (e.g. tadah explain refit.refit_mode) for
the full description of any key.
OPTIONS:
--outfile, -o <file>
Output file name for the fitted native Tadah potential.
Number of arguments: Min 1, Max 1
Default: pot.tadah
Description:
The output file to be written. Multiple files can be specified if the command
produces more than one output.
Examples:
- output.tadah
--hpofileout <file>
Output file name for the generated tadah hpo starter target file.
Number of arguments: Min 1, Max 1
Default: refit.hpotarget
Examples:
- refit.hpotarget
--func {phi|rho|F}
Curve selector for tadah refit --edit: phi (pair, CGRID2B), rho (density, CGRIDMB/AMPGRIDMB) or F (embedding, CEMBFUNC).
Number of arguments: Min 1, Max 1
Needs: edit
Examples:
- phi
- rho
- F
--add <centre>
tadah refit --edit: insert a basis function at this centre (r in Angstrom for phi/rho, electron density for F) with coefficient 0 — the potential is unchanged until HPO varies the new coefficient.
Number of arguments: Min 1, Max 1
Needs: edit
Excludes: remove
Description:
Insert one basis function into the curve selected by --func, centred at the
given position. The new coefficient (weight for phi/F, density amplitude for
rho) is 0, so the edited potential predicts EXACTLY like the input — the new
basis function only adds capacity for a subsequent tadah hpo run (its
OPTIM line is emitted in the regenerated hpotarget).
Knot families (Knot5/Knot3): the knot position is the only shape parameter
(--eta is rejected; widths are a pure gauge). --deg 3|5 selects the knot
degree (default 5). Adding a radial knot beyond the current largest knot
EXTENDS the effective cutoff — RCUT2B/RCUTMB are updated accordingly.
Blip families (Blip/Blip5): the inverse width defaults to the mean of the
two nearest neighbours' widths (--eta overrides). A blip whose support lies
entirely beyond RCUT is rejected; one whose support crosses RCUT is truncated
there (warning) — RCUT is never changed for blip potentials.
Examples:
- 2.75
--remove <centre>
tadah refit --edit: remove the basis function nearest this centre; the two neighbouring coefficients are least-squares adjusted to track the original curve (value + 1st + 2nd derivative).
Number of arguments: Min 1, Max 1
Needs: edit
Excludes: add
Description:
Remove the basis function of the --func curve whose centre is nearest to the
given position (the chosen centre is reported). Unless the removed
coefficient is exactly 0, the two remaining basis functions nearest in centre
are least-squares adjusted against the original curve's value, first and
second derivative, sampled densely over the region the removed function
controlled. Removal is inherently lossy — the report prints the residual
before/after compensation; expect model performance to change and re-validate.
Removing the OUTERMOST radial knot of a knot-family potential shrinks the
effective cutoff (RCUT2B/RCUTMB follow the largest remaining knot); the tail
between the new and old cutoff cannot be compensated (warning).
Examples:
- 2.75
--eta <inverse width>
tadah refit --edit --add, blip families only: inverse width of the inserted basis function (default: mean of the neighbouring widths). Rejected for knot families (width is a pure gauge).
Number of arguments: Min 1, Max 1
Needs: add
Examples:
- 1.8
--deg {3|5}
tadah refit --edit --add, knot families only: degree of the inserted knot — 5 (quintic, C4, default) or 3 (cubic, C2; materialises the per-knot KDEG* degree array). Rejected for blip families.
Number of arguments: Min 1, Max 1
Needs: add
Examples:
- 3
- 5
--pct <pct> and/or <KEY>=<pct> [...]
tadah refit --retarget: +-percent half-width for the rewritten OPTIM bounds. A bare number sets the global default; KEY=N overrides one key group, e.g. --pct 10 FIXWEIGHT=2.
Number of arguments: Min 1, Max MAX_INT
Needs: retarget
Examples:
- 10
- FIXWEIGHT=2
- 10 CGRID2B=2
--set '<KEY>(<i>)=<lo>,<hi>' [...]
tadah refit --retarget: absolute bounds for one OPTIM parameter, e.g. --set 'CGRID2B(3)=2.1,2.4' (repeatable; applied after --pct; comment state preserved).
Number of arguments: Min 1, Max MAX_INT
Needs: retarget
Examples:
- 'CGRID2B(3)=2.1,2.4'
- 'FIXWEIGHT(7)=-50,-10'
--in-place
tadah refit --retarget: overwrite the input hpotarget file (atomic temp-write + rename) instead of writing a new file. Mutually exclusive with -o.
Needs: retarget
Excludes: outfile
Default: false
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
refit.setfl_out <file>
Output setfl file written from the native fitted functions (tadah refit).
Number of arguments: Min 1, Max 1
Examples:
- refit.eam.alloy
refit.refit_basis <string>
Flexible-basis family used by tadah refit. Family x mode matrix — DEFAULT: 'Knot5' in compact mode, 'Blip' in dense mode (and as the automatic fallback when the compact fitter is unavailable, i.e. non-Ceres builds; an explicit REFIT_BASIS always wins). 'Blip' (cubic B-spline bumps, C2; dense AND compact modes; the most validated family) | 'Blip5' (M6 quintic B-spline bumps, C4, local support; dense AND compact; measured: best Fe elastic constants of all families but material-dependent — one reference element (Al) degraded to ~4 GPa C11; always verify with the faithfulness battery) | 'Knot3' (one-sided CUBIC knot functions (t-r)_+^3 — the Mendelev/Ackland form, exact for knotted-cubic source tables; compact only) | 'Knot5' (one-sided QUINTIC knot functions, C4; the RECOMMENDED opt-in: best measured worst-case elastic constants of all families (1.6 vs Blip's 2.3 GPa across the 5 reference EAMs) with every E-V observable in tolerance; compact only) | 'KnotMix' (EXPERIMENTAL auto mode: quintic knot atoms by default, cubic atoms inserted where they win the per-insertion energy contest. Measured: best-in-class E-V faithfulness, but the greedy detector deploys cubics liberally (~40-60%) and the localized C2 sawtooth degrades elastic constants vs pure Knot5 — prefer Knot5 unless E-V is your only target; compact only) | 'Gaussian' (EXPERIMENTAL/UNVALIDATED for refit: never gated through the LAMMPS faithfulness battery; hard-cutoff truncation leaves a value discontinuity at rcut; dense mode only — prefer any other family). Compact-only families need the Ceres-enabled HPO build. NOTE for HPO: SGRID* width entries are a pure gauge for the Knot* families (pinned 1.0) — do not add OPTIM blocks on them.
Number of arguments: Min 1, Max 1
Examples:
- Blip
- Blip5
- Knot3
- Knot5
- KnotMix
refit.refit_level <string>
Grid-accuracy preset for tadah refit: coarse | balanced | fine | accurate.
Number of arguments: Min 1, Max 1
Examples:
- balanced
- fine
refit.n2b <unsigned integer>
Override: number of two-body basis functions in tadah refit.
Number of arguments: Min 1, Max 1
Examples:
- 50
refit.nrho_basis <unsigned integer>
Override: number of density basis functions in tadah refit.
Number of arguments: Min 1, Max 1
Examples:
- 40
refit.nf_basis <unsigned integer>
Override: number of embedding basis functions in tadah refit.
Number of arguments: Min 1, Max 1
Examples:
- 30
refit.optim_pct <double>
Default +-percent half-width for the OPTIM bounds emitted by tadah refit.
Number of arguments: Min 1, Max 1
Examples:
- 5.0
refit.output_grid_scale <double>
Scale factor for the output setfl grid density (1.0 = same as input).
Number of arguments: Min 1, Max 1
Examples:
- 1.0
- 2.0
refit.refit_tol_ambient <double>
tadah refit faithfulness tolerance (meV/atom) for the ambient crystal self-test (E-V, a/a0 0.95-1.10). The basis auto-escalates until met. Default 0.1.
Number of arguments: Min 1, Max 1
Examples:
- 0.5
refit.refit_tol_compressed <double>
tadah refit faithfulness tolerance (meV/atom) for the COMPRESSED crystal self-test (a/a0 0.75-0.95, V/V0 down to ~0.42). The basis auto-escalates until met. Default 1.0.
Number of arguments: Min 1, Max 1
Examples:
- 5.0
refit.refit_max_escalations <unsigned integer>
tadah refit maximum automatic basis-escalation rounds when the self-test is above tolerance (0 disables escalation). Default 4.
Number of arguments: Min 1, Max 1
Examples:
- 4
- 0
refit.refit_placement <string>
tadah refit basis placement: 'window' (default; basis concentrated on the physically reachable pair-distance/density window, small uniform tail allocation) or 'uniform' (legacy single uniform grid over the full tabulated range).
Number of arguments: Min 1, Max 1
Examples:
- window
- uniform
refit.refit_reach_smin <double>
tadah refit reachability probe: smallest linear compression a/a0 the fit must stay faithful at (0.75 ~ V/V0=0.42, multi-hundred-GPa regime). Sets the reachable pair-distance/density window and the self-test span. Default 0.75.
Number of arguments: Min 1, Max 1
Examples:
- 0.75
- 0.65
refit.refit_reach_margin <double>
tadah refit safety margin multiplying the maximum reachable embedding density when choosing the F(rho) fit window. Default 1.25.
Number of arguments: Min 1, Max 1
Examples:
- 1.25
refit.refit_constrain_f0
tadah refit: pin the embedding to the table's F(0) (isolated-atom reference) with a constraint row. Default true.
Default: true
refit.refit_r_lo_frac <double>
tadah refit inner radial fit bound as a fraction of rcut (default 0.20). Below it the round-trip setfl tabulates a smooth C2-matched repulsive continuation and the native pot.tadah is outside its validity domain.
Number of arguments: Min 1, Max 1
Examples:
- 0.20
- 0.15
refit.refit_mode <string>
tadah refit fitting mode: 'compact' (DEFAULT; optimised blip centres/widths via ladder + analytic-gradient Ceres polish, ~30-120 params — the HPO-friendly search space; requires the Ceres-enabled HPO build, else falls back to dense with a warning) or 'dense' (region-uniform grids + auto-escalation, ~300-450 params, fastest fit).
Number of arguments: Min 1, Max 1
Examples:
- dense
- compact
refit.refit_log <string>
tadah refit optimisation-log file (default refit_opt.log): one timestamped, immediately-flushed line per ladder rung (the rung reports its winning candidate's metric/rmse/d1/d2 progression across the insert->explore->refine->merge checkpoints, any coalescence-guard merge count, and each stage's stop reason + work done) plus the global seed, joint-refinement (FUSE) summary and crystal self-test, inspectable DURING the fit.
Number of arguments: Min 1, Max 1
Examples:
- refit_opt.log
refit.refit_compact_nmax <unsigned integer> [<unsigned integer> ...]
tadah refit compact mode: per-function basis (blip/knot) ceiling for the EXPLORE ladder. Give ONE value (applies to all three functions) or THREE values 'phi rho F' (separate per-function ceilings, e.g. 39 5 27). Default 40. Only EXPLORE grows the basis; REFINE/FUSE only refine the existing basis.
Number of arguments: Min 1, Max MAX_INT
Examples:
- 40
- 39 5 27
refit.refit_compact_opt_every <unsigned integer>
tadah refit compact mode, Knot5 family: run the full per-rung optimisation (explore + polish) only every K-th ladder rung; intermediate rungs grow by energy-aware insertion + linear solve, with one final full optimisation of the best fit. Default 1 (optimise every rung — matrix-measured most consistent). 999 = insertion-only growth + final optimisation: best results when no ladder stalls (measured Ta: Cij <= 0.09 GPa), but can underfit if a ladder stalls during growth.
Number of arguments: Min 1, Max 1
Examples:
- 1
- 3
refit.refit_compact_stall <unsigned integer>
tadah refit compact mode: stop the ladder after this many consecutive rungs without energy-metric improvement. Default 6 (Blip) / 12 (Knot5).
Number of arguments: Min 1, Max 1
Examples:
- 6
- 12
refit.refit_compact_insert_topk <unsigned integer>
tadah refit compact mode, Knot5 family: energy-aware insertion — evaluate the top-k separated curve-residual peaks and insert at the one that most improves the crystal energy metric. Default 3 for Knot5, 1 (curve peak only) for Blip.
Number of arguments: Min 1, Max 1
Examples:
- 1
- 3
refit.refit_compact_share <double>
tadah refit compact mode: fraction of the REFIT_TOL_* budget each function must reach alone during its ladder (the joint refinement then handles cross-function coupling). Default 0.5.
Number of arguments: Min 1, Max 1
Examples:
- 0.5
refit.refit_compact_seed <unsigned integer>
tadah refit compact mode: RNG seed for the jittered ladder restarts (deterministic reruns). Default 12345.
Number of arguments: Min 1, Max 1
Examples:
- 12345
refit.refit_compact_samples <unsigned integer>
tadah refit compact mode: number of uniform sample points per function across its fit window. The VALUE RMSE and the 1st/2nd-derivative (d1/d2) RMSEs — and the curve objective (REFIT_OBJECTIVE curve) — are all evaluated on THIS shared grid: at each point the EAM cubic-spline value and its analytic 1st/2nd derivatives are the targets. More points = finer RMSE estimate and finer curve fit but slower (each closed-form VARPRO solve is O(samples * basis)); fewer = faster, coarser. Default 800. Clamped up to max(50, 4 x REFIT_COMPACT_NMAX). Independent of the energy E-V scan and the OUTPUT_GRID_SCALE setfl output grid.
Number of arguments: Min 1, Max 1
Examples:
- 800
- 400
- 1600
refit.refit_compact_jitters <unsigned integer>
tadah refit compact mode: number of randomised warm restarts per ladder rung. Each rung runs jitters+1 candidates (1 warm start + this many perturbed restarts) through the full EXPLORE -> REFINE pipeline and keeps the energy-metric-best — exploration that stops the local search locking into a bad basin. This is why the coalescence guard can fire several times within one rung (once per candidate). Default 2 (3 candidates/rung). 0 = warm start only (cheaper, less robust).
Number of arguments: Min 1, Max 1
Examples:
- 2
- 0
- 4
refit.refit_compact_merge <string>
tadah refit compact mode, Knot families: coalescence guard. 'true' applies a soft anti-coalescence penalty during EXPLORE plus a post-REFINE merge of near-coincident knot pairs that re-inserts a fresh knot at the worst residual. 'auto' (default) sets it OFF for REFIT_OBJECTIVE curve and ON for REFIT_OBJECTIVE energy. 'false' keeps it off. Knot families only.
Number of arguments: Min 1, Max 1
Default: auto
Examples:
- auto
- true
- false
refit.refit_objective <string>
tadah refit compact mode: what the WHOLE fitting chain (seed, EXPLORE, REFINE, FUSE, and the rung selection / stall / stop decisions) optimises toward. 'energy' (default) = the crystal energy metric (current behaviour). 'curve' = a normalised combined RMSE of the fitted VALUE + 1st-derivative + 2nd-derivative against the tabulated function (each term divided by the table's own RMS over the window, then RMS-combined). In curve mode the coefficients are solved from a stacked value+d1+d2 least-squares, the knot positions are searched with the configured EXPLORE optimiser on that objective, FUSE is a per-function curve refine that drops the energy term, and the energy metric is unused end-to-end. The target 1st/2nd derivatives are the EXACT analytic derivatives of the setfl cubic spline (no finite differencing). OPTIMISER POLICY: curve mode HONOURS the configured optimiser at every stage (EXPLORE inner, REFINE, FUSE; ENABLED false or ALGO NONE skips a stage); the per-stage legal set is enforced at parse time and the actual stack is logged. The pressure-relaxed weighting (REFIT_CURVE_WEIGHTING, ON by default) concentrates the fit where the crystal actually probes (ambient r/rho) so an aggressive least-squares optimiser does not over-fit the unprobed high-magnitude regions and wreck the crystal. FUSE keeps NO crystal E-V coupling (curve mode is independent of energy mode). Note the ladder grows until stall / n_max (the curve score has no tolerance threshold).
Number of arguments: Min 1, Max 1
Default: energy
Examples:
- energy
- curve
refit.refit_curve_deriv_weight <double>
tadah refit compact mode, REFIT_OBJECTIVE curve only: weight of EACH derivative block (1st and 2nd) RELATIVE to the value block in the curve objective (both the stacked coefficient solve and the rung-selection score). 0 (DEFAULT) = pure VALUE fit, which is crystal-faithful: LAMMPS computes the crystal energy from the curve VALUES, so a value-only fit reproduces the crystal as well as energy mode (measured Ti: cohesive +3.8 meV/atom, E-V 5-6 meV). ANY nonzero weight degrades the crystal sharply (measured: 0.01 -> -15, 0.1 -> -69, 1.0 -> +37 meV/atom cohesive) because the relative normalisation lets even a 1% derivative term trade away the large ABSOLUTE value error of a high-magnitude function like F. Raise it ONLY to capture the 1st/2nd-derivative SHAPE at the EXPENSE of crystal energy. 1.0 = value/d1/d2 equal (the original, crystal-wrecking curve mode). Ignored unless REFIT_OBJECTIVE=curve.
Number of arguments: Min 1, Max 1
Default: 0.0
Examples:
- 0.0
- 0.1
- 1.0
refit.refit_curve_weighting
tadah refit compact mode, REFIT_OBJECTIVE curve only: pressure-relaxed curve weighting (ON by default). Concentrates the fit where the crystal actually probes and relaxes it toward the high-pressure extremes, so a fixed knot budget spends its accuracy where it matters: phi(r) and rho(r) are weighted 1 between the ambient nearest-neighbour distance r_amb and the cutoff, ramping smoothly down to REFIT_CURVE_RELAX toward smaller r (compression); F(rho) is weighted 1 from rho=0 up to the ambient density rho_amb, ramping down to the floor for higher rho (compression). r_amb and rho_amb are derived self-contained from the lattice geometry and the EAM tables (no crystal energy-volume scan dependency). The weights apply to BOTH the stacked value+d1+d2 coefficient solve AND the rung-selection metrics, so fit and selection agree. false = uniform weighting (legacy curve mode). This key is rejected in energy mode. Multiplies with REFIT_CURVE_DERIV_WEIGHT (orthogonal: deriv_weight scales d1/d2 vs value; this scales per-region).
Default: true
refit.refit_curve_relax <double>
tadah refit compact mode, REFIT_OBJECTIVE curve with REFIT_CURVE_WEIGHTING on: the floor weight (a fraction greater than 0 and at most 1) that the pressure-relaxed profile ramps DOWN to in the compressed / high-pressure regions (phi/rho below r_amb, F above rho_amb). 1.0 reproduces uniform weighting, smaller values relax the fit harder away from ambient (default 0.05). The ramp is a C1 smoothstep between the ambient band (weight 1) and the window edge (weight equal to this floor). Rejected in energy mode.
Number of arguments: Min 1, Max 1
Default: 0.05
Examples:
- 0.05
- 0.1
- 0.02
refit.optimizer <string> [<string> ...]
Optimiser sub-block for a tadah refit stage (EXPLORE/REFINE/FUSE). A multi-line OPTIMIZER ... ENDOPTIMIZER block nested INSIDE a stage block; takes LIB <name> / ALGO <name> plus stopping criteria (MAXEVAL, FTOL_REL/FTOL_ABS, XTOL_REL/XTOL_ABS, GTOL, ...) in the same syntax as the tadah hpo --hpotarget OPTIMIZER block, and an optional nested INNER ... ENDINNER for the per-rung local search. A top-level OPTIMIZER block is rejected (it must be nested in a stage).
Number of arguments: Min 1, Max MAX_INT
Examples:
- see HPO_REFIT_2B_EAM/REDESIGN/configs (OPTIMIZER nested in EXPLORE/REFINE/FUSE)
refit.init <string> [<string> ...]
tadah refit INIT stage block (INIT ... ENDINIT, no optimisation). Declares manual / anchored knots or blips per channel: <PHI|RHO|F> <MANUAL <mu> [<eta>] | XMIN | XMAX | YMIN | YMAX | SMAX | CMAX> [PIN]. PIN freezes that position in EXPLORE/REFINE/FUSE (the linear coefficient is still solved). Captured verbatim; parsed by the refit engine.
Number of arguments: Min 1, Max MAX_INT
Examples:
- INIT / PHI XMIN PIN / ENDINIT
refit.explore <string> [<string> ...]
tadah refit EXPLORE stage block (EXPLORE ... ENDEXPLORE): structure search + basis growth (absorbs the old GLOBAL stage at rung 0). Takes MAX_ADD <n> (max basis added per function) and a nested OPTIMIZER block (default global MLSL with an INNER local SBPLX). Captured verbatim; parsed by the refit engine.
Number of arguments: Min 1, Max MAX_INT
Examples:
- EXPLORE / MAX_ADD 38 / OPTIMIZER ... ENDOPTIMIZER / ENDEXPLORE
refit.refine <string> [<string> ...]
tadah refit REFINE stage block (REFINE ... ENDREFINE): per-rung high-precision local polish (Ceres LM/DOGLEG, or NLOPT/DLIB local). Takes a nested OPTIMIZER block. Captured verbatim; parsed by the refit engine.
Number of arguments: Min 1, Max MAX_INT
Examples:
- REFINE / OPTIMIZER ... ENDOPTIMIZER / ENDREFINE
refit.fuse <string> [<string> ...]
tadah refit FUSE stage block (FUSE ... ENDFUSE): final joint refinement of all three functions against curve + crystal energy-volume residuals (least-squares only: Ceres LM/DOGLEG or NONE). Takes a nested OPTIMIZER block. Captured verbatim; parsed by the refit engine.
Number of arguments: Min 1, Max MAX_INT
Examples:
- FUSE / OPTIMIZER ... ENDOPTIMIZER / ENDFUSE
--rcut2b <double>
tadah refit --retarget: declare the pair channel's fixed cutoff in ONE step — recentre the file's OPTIM RCUT2B reference line on this value and bind the bump-support cap against it, so the rewritten CGRID2B/SGRID2B boxes are truncated to c + w/eta <= this value. Any ACTIVE OPTIM RCUT2B line is commented out with a warning: on a bump channel the support gate keeps every bump inside the cutoff's LOW bound, so searching the cutoff cannot affect the model. Remember to set the same RCUT2B in the training config. Ignored with a warning on knot channels, where RCUT2B is derived from the largest knot.
Number of arguments: Min 1, Max 1
Examples:
- 6.0
--rcutmb <double>
tadah refit --retarget: the density channel's twin of --rcut2b — recentre the OPTIM RCUTMB reference and truncate the CGRIDMB/SGRIDMB boxes to the declared cutoff.
Number of arguments: Min 1, Max 1
Examples:
- 6.0
OPTIONS::input
Provide the EAM potential to refit (or a config file declaring it), or select an editing mode on existing refit outputs (--edit/--retarget).
--edit <file>
Edit mode for tadah refit: path to an existing refit potential (pot.tadah) to add/remove one basis function (use with --func and --add or --remove).
Number of arguments: Min 1, Max 1
Excludes: retarget
Description:
Switches tadah refit into potential-editing mode: instead of refitting a
tabulated EAM file, load an existing knot/blip potential and add or remove
ONE basis function per invocation.
Supported potentials: the pair descriptor must be a refit family
(D2_Knot5 / D2_Blip / D2_Blip5), with BIAS false and NORM false. The
many-body term is optional:
- none (a pure two-body potential): --func phi edits the pair curve;
- DM_REAM (a tadah refit EAM): all three curves are editable;
- any other many-body descriptor: only --func phi (the pair channel) —
the many-body keys and its WEIGHTS block are preserved untouched.
Use with:
- --func {phi|rho|F}: which curve to edit (pair / density / embedding;
rho and F require a DM_REAM many-body term).
- --add <centre>: insert a basis function at this position with coefficient
0 — the potential's predictions are BIT-IDENTICAL to the input (value, all
derivatives, extrapolation); the new coefficient becomes an extra search
dimension in the regenerated hpotarget file.
- --remove <centre>: delete the basis function whose centre is nearest to
<centre>; the two neighbouring coefficients are least-squares adjusted to
track the original curve's value, first and second derivative over the
affected region. Removal is lossy by design — expect small changes.
Outputs: an edited potential (-o; defaults to pot_edited.tadah so the input
is never silently overwritten) and a regenerated hpotarget (--hpofileout;
defaults to refit_edited.hpotarget). For knot-family channels RCUT2B/RCUTMB
are recomputed from the basis (effective cutoff = largest knot), so adding
a knot beyond the current largest one widens the effective cutoff.
Examples:
- pot.tadah
--retarget <file>
Retarget mode for tadah refit: rewrite the OPTIM search bounds of an existing hpotarget file (use with --pct, --set, -o or --in-place).
Number of arguments: Min 1, Max 1
Excludes: edit
Description:
Switches tadah refit into hpotarget-retargeting mode: read an existing
hpotarget file (as written by tadah refit or a previous --retarget run) and
rewrite the bounds of every OPTIM line — active AND commented, preserving the
comment state — around the recovered parameter values.
Bound width control:
- --pct <N>: global +-percent half-width (default: OPTIM_PCT, else 5).
- --pct KEY=N: per-key override, e.g. --pct FIXWEIGHT=2 (repeatable; mix
with the global value: --pct 10 CGRID2B=2).
- --set 'KEY(i)=lo,hi': absolute bounds for one parameter (repeatable,
applied last).
- --rcut2b <r> / --rcutmb <r>: declare a bump channel's fixed cutoff in the
same run — recentre the file's OPTIM RCUT reference on r and truncate the
rewritten CGRID/SGRID boxes to the bump-support rule c + w/eta <= r
(active OPTIM RCUT lines are commented out with a warning; set the same
RCUT in the training config).
Everything that is not an OPTIM line is preserved byte-for-byte. The output
goes to -o (default: <input>_edited.hpotarget) or back into the input with
--in-place. For knot-family potentials the commented RCUT2B/RCUTMB lines are
recomputed from the largest knot position (the true effective cutoff).
Examples:
- refit.hpotarget
refit.input.eam <file>
Input tabulated EAM potential (setfl: eam/alloy or eam/fs) for tadah refit.
Number of arguments: Min 1, Max 1
Examples:
- Ta2_Ravelo_2013.eam.alloy
- Fe_2.eam.fs
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
EXAMPLES:
- tadah refit -c refit.cfg
- tadah refit -c refit.cfg -v 2
- tadah refit --edit pot.tadah --func phi --add 2.75
- tadah refit --edit pot.tadah --func F --remove 0.9
- tadah refit --retarget refit.hpotarget --pct 10 FIXWEIGHT=2
- tadah refit --retarget refit.hpotarget --pct 10 --rcut2b 6.0 --rcutmb 6.0 -o wide.hpotarget
- tadah refit --retarget refit.hpotarget --set 'CGRID2B(3)=2.1,2.4' --in-place
train
DESCRIPTION:
Train a model.
LONG DESCRIPTION:
Train a model using either a configuration file or a task file. By default,
it trains on energies; however, forces and stresses can also be included.
This command requires a configuration file and yields a trained interatomic
potential which can be used with Tadah! or for molecular
dynamics simulations in LAMMPS via pair_style tadah.
OPTIONS:
--outfile, -o <file>
Output file name for the trained model.
Number of arguments: Min 1, Max 1
Default: pot.tadah
Description:
Output file name for the trained model.
Examples:
- output.tadah
--verbose, -v <unsigned integer>
Verbosity level. 0-2: ERROR, WARNING, INFO.
Number of arguments: Min 1, Max 1
Default: 1
Description:
Verbosity level. 0: ERROR, 1: WARNING, 2: INFO. The verbosity level controls
the amount of information printed during execution. Higher levels provide
more detailed output.
Examples:
- 2
--force, -F
Include forces.
Default: false
--stress, -S
Include stresses.
Default: false
--uncertainty
Output uncertainty estimates.
Default: false
--lscale <double>
Uniform length rescale factor applied to atomic positions, cell, and reference forces at load time.
Number of arguments: Min 1, Max 1
Default: 1.0
Description:
Multiplies atomic positions and cell vectors by this factor at the moment a
dataset is loaded for training, prediction, or HPO. Reference forces are
divided by the factor (chain rule on E(r)); stresses (stored as virial in
energy units) are invariant under uniform length rescaling. The chosen factor
is persisted into pot.tadah so future tadah predict and tadah hpo runs
apply the same transformation. Use --no-lscale at predict time to override.
LSCALE is a training-side concept: the LAMMPS pair_style does NOT re-apply
LSCALE. The user is expected to provide LAMMPS positions at the scale that
matches the trained model (e.g. experimental lattice).
Examples:
- 1.0030
--eshift <double> [<double> ...]
Per-atom reference energy to subtract from each configuration.
Number of arguments: Min 1, Max MAX_INT
Description:
Per-element reference energies. If there are multiple species, the number of
values must match the number of species (sorted by Z). At load time the total
energy of each configuration is reduced by sum_Z N_Z * ESHIFT[Z], so an
isolated-atom config with energy E_atom and ESHIFT[Z]=E_atom yields a
post-shift energy of zero. Used by tadah train, tadah predict, tadah hpo,
and tadah data balance. Persisted into pot.tadah for prediction round-trip.
Examples:
- 0.5
- 0.5 -0.1
--eshift-atom
Derive ESHIFT from isolated-atom configurations in the dataset (mean per Z).
Default: false
Description:
Scans the loaded dataset for single-atom configurations (natoms == 1), groups
them by atomic number, and sets ESHIFT[Z] to the mean per-Z energy. If a
species has no isolated-atom config in the dataset, ESHIFT[Z] = 0 for that
species and a WARNING is logged. If multiple isolated-atom configs of the same
Z disagree by more than 1e-3 eV, an INFO line records the spread.
Mutually exclusive with explicit ESHIFT and ESHIFT_DBATOM.
--eshift-dbatom
Derive ESHIFT by least-squares atomic-energy fit over the database.
Default: false
Description:
Fits per-element reference energies by least squares: minimise
||y - M beta||^2 where y[i] is the total energy of configuration i and
M[i, k] is the count of species k in configuration i. The fitted beta_k
becomes ESHIFT[Z(k)]. More robust than ESHIFT_ATOM when the dataset has no
isolated-atom configs but does have compositional diversity.
Mutually exclusive with explicit ESHIFT and ESHIFT_ATOM.
--efilter <E_min_per_atom> <E_max_per_atom>
Drop configurations whose per-atom energy is outside [E_min, E_max] (eV).
Number of arguments: Min 2, Max 2
Description:
Outlier filter applied at load time before any energy-shift derivation or
training-weight assignment, so outliers do not poison ESHIFT_ATOM /
ESHIFT_DBATOM / EWEIGHT_TEMP. The threshold is compared against E/N_atoms
(per-atom energy). Both bounds must be supplied. To disable, omit the key.
Examples:
- -12.0 -2.0
--ffilter <double>
Drop configurations where any atomic force magnitude exceeds this value (eV/Å).
Number of arguments: Min 1, Max 1
Description:
Outlier filter applied at load time. A configuration is dropped if any single
atom has ‖F‖ > FFILTER. Useful for catching unconverged SCF or otherwise
broken DFT runs.
Examples:
- 20.0
--wdbfile <double> [<double> ...]
Per-dataset weight multipliers, one per DBFILE entry.
Number of arguments: Min 1, Max MAX_INT
Description:
Multiplies eweight, fweight, and sweight of every configuration in the
corresponding DBFILE by the given factor. Use to bias training toward or away
from particular datasets. Composes multiplicatively with WDBFILE_AUTO.
Examples:
- 1.0 0.5 0.1
--wdbfile-auto <double>
Auto size-balance datasets: per-config weight multiplied by 1/N_i^alpha.
Number of arguments: Min 1, Max 1
Default: 0.0
Description:
Rebalances per-dataset contributions to the training loss by multiplying each
configuration's weight by N_i^(-alpha), where N_i is the number of (post-
filter) configurations in dataset i. alpha=0 disables (default). alpha=0.5
is the recommended starting point (sqrt-inverse, soft balance). alpha=1
fully equalises aggregate dataset contribution. Composes multiplicatively
with user-given WDBFILE.
Examples:
- 0.5
- 1.0
--eweight-temp <double>
Boltzmann reweighting temperature in Kelvin (multiplies eweight).
Number of arguments: Min 1, Max 1
Description:
After ESHIFT is applied, multiplies each configuration's eweight by
exp(-(E/N - E_min)/(kB * T)) where E_min is the minimum per-atom energy in
the dataset and kB = 8.617333262e-5 eV/K. Emphasises low-energy
configurations. Composes multiplicatively with the per-structure eweight
already in the dataset file. Omit the key to disable.
Examples:
- 300
- 1000
--zero-com-force
Subtract per-config mean force so each configuration has zero net force.
Default: false
Description:
Per configuration, subtracts the mean force from each atom so that the sum of
forces over the configuration is exactly zero. Standard DFT post-processing
trick to remove residual translational forces from incomplete relaxation/SCF.
OPTIONS::input
Provide a configuration file for a single task or a complete tasks file.
--config, -c <file>
Path to a configuration file.
Number of arguments: Min 1, Max 1
Examples:
- config.tadah
- ../config.tadah
- /path/to/config.tadah
--task, -t <file>
A file containing task(s) to be executed.
Number of arguments: Min 1, Max 1
Excludes: ALL
Description:
The task file is a convenient way to specify multiple tasks without having to
provide all the command-line arguments for each task. The task file should be
in the same format as the configuration file, but it can also include additional
information such as the task name and any specific parameters for that task.
A task in a task file begins with the keyword 'TASK' followed by the task name.
The task name is simply a command to be executed or both command and subcommand.
The lines following the TASK keyword should contain parameters required for
the task specified above. For example, CLI --verbose 2 is 'VERBOSE 2' in the
task file.
# Example TASK file containing two tasks:
# Global options
NUMERIC 14 # output precision
VERBOSE 2 # verbosity level
TASK predict
DBFILE db1.tadah db2.tadah db3.tadah
DBFILE db4.tadah db5.tadah db6.tadah
FORCE true
ANALYTICS true
TASK data print
STRUCTURE crystal1.cif crystal2.cif
Examples:
- path/to/tasks.tadah
EXAMPLES:
- tadah train -c config.tadah
- tadah train -c config.tadah --force --stress
- tadah train -c config.tadah --verbose 2 --outfile potential.tadah
- tadah train --task tasks.tadah