Using the command line tools
If you have installed via Conda, and activated the relevant environment, the command line tool apitofsim should be installed into your path.
If you are using uv you may need to run uv run apitofsim instead.
apitofsim
The command line interface to apitofsim
Usage:
Options:
Subcommands
- convert: Commands to convert between different file formats
- db: Commands to work with the database-backed workflow
- generate: Commands to inspect different files
- inspect: Commands to inspect different files
apitofsim convert
Commands to convert between different file formats
Usage:
Options:
Subcommands
- config: Convert .in configuration files to .toml
apitofsim convert config
Convert .in configuration files to .toml
Usage:
Options:
apitofsim db
Commands to work with the database-backed workflow.
Typically you will prepare your dataset into a database, then run it, and then use report and plot to analyze the results.
Usage:
Options:
Subcommands
- plot: Commands for plotting results
- prepare: Prepare the database for use
- refresh-views: Refresh views in the database at path DATABASE (please ignore)
- report: Produce an Excel-friendly CSV report from the database
- run: Run the simulations according to the prepared database
apitofsim db plot
Commands for plotting results
Usage:
Options:
Subcommands
- spectrogram: Plot a spectrogram for a single cluster in an experiment
- spectrogram-many: Plot a spectrogram for each cluster in an experiment
- survival: Plot survival rates for each parent cluster in an experiment
apitofsim db plot spectrogram
Output to PNGOUT a spectrogram of the results for single cluster / experiment using the database at path DATABASE.
Usage:
Options:
--filter-parent TEXT Only run pathways with a specified common
name for the parent cluster
--filter-config TEXT Only run the experiment using the parameters
in the named configuration
--model-transmission [old|new_neg|new_pos]
--label [all|nonzero|threshold|none]
Add labels indicating the cluster
--label-threshold FLOAT specified threshold for labeling clusters
when --label=threshold
--help Show this message and exit.
apitofsim db plot spectrogram-many
Output to DIROUT a spectrogram per cluster using the results from single experiments using the database at path DATABASE.
Usage:
Options:
--filter-config TEXT Only run the experiment using the parameters
in the named configuration
--model-transmission [old|new_neg|new_pos]
--label [all|nonzero|threshold|none]
Add labels indicating the cluster
--label-threshold FLOAT specified threshold for labeling clusters
when --label=threshold
--help Show this message and exit.
apitofsim db plot survival
Output to PNGOUT a bar chart of the survival rate for each cluster in the database at path DATABASE.
Usage:
Options:
apitofsim db prepare
Prepare the database according to MODE at path DATABASE using the json configuration file at path CONFIG.
Typically, you will be creating an database in order to run simulation experiments, and so --db-type should be kept as --db-type=experiment.
MODE can be create or append, depending on whether you want to create a new database or append to an existing one.
You may choose to --warm your database, so that histogramming is done now, in advance of the simulation itself.
The CONFIG file specifies a TOML formatted file containing both where to import the information about the cluster and pathways from, and the parameters to use for the simulation.
Pathways
For pathways, you can specify the type as "legacy_glob" or "csv".
The "legacy_glob" type imports pathways from the legacy .in files matching a glob pattern. The per-cluster data is then taken either from .dat files specified in the .in file or ORCA or Gaussian outputs files next to the .in file.
[[pathways]]
type = "legacy_glob"
# An optional prefix to add to the common names of all clusters imported here
prefix = ""
# A glob pattern to use to find .in files. The wildcard * matches any number of characters, while ** can span directories.
path = "/path/to/**/*.in"
# Paths specified in the .in files are relative to the .in file directory.
cwd = "."
[pathways.clusters]
# By default, all attributes are taken from the gaussian source
default_source = "gaussian"
# Individual attributes can be taken from different sources and combined using simple expressions. Here, the electronic energy is taken as the sum of the final single point energy from orca and the zero point energy from gaussian.
electronic_energy = "orca.final_single_point_energy + gaussian.zero_point_energy"
# Here the sources for cluster information are specified.
# The dat source is actually unused in this example
[pathways.clusters.sources.dat]
# The ORCA source is only used for part of the electronic energy
[pathways.clusters.sources.orca]
# append_to_common_prefix means that the common name of the cluster will be taken as the .in file name with .out appended
append_to_common_prefix = ".out"
# Finally, the Gaussian source, where most attributes are taken from is specified
[pathways.clusters.sources.gaussian]
append_to_common_prefix = ".log"
For the "csv" type, you specify the pathways and clusters in separate CSV files, with, as above, the information about how to combine sources specified in the toml config file.
[[pathways]]
type = "csv"
pathways_path = "pathways.csv"
clusters_path = "clusters.csv"
# These are the same as legacy_glob, see above
[pathways.clusters]
default_source = "gaussian"
electronic_energy = "orca.final_single_point_energy + gaussian.zero_point_energy"
[pathways.clusters.sources.orca]
append_to_common_prefix = ".out"
[pathways.clusters.sources.gaussian]
append_to_common_prefix = ".log"
Then clusters.csv associates filename prefixes with common names for clusters:
While pathways.csv relates the parent clusters to their products for each pathway:
parent,product1,product2
2A_2SA_negative,1A_1SA_negative,1A_1SA_neutral
2A_3SA_negative,1A_1SA_negative,1A_2SA_neutral
Note that apitofsim generate pathways can be used to generate these CSV files from a directory of QC output files.
They can then be edited, e.g. with Excel, to remove unwanted clusters and pathways.
Parameters
For the simulation parameters, you can specify one or more [[configs]] sections, each with a name field and the values of all parameters.
You can put common parameters in the default_config section, so that each [[configs]] section inherits these as overridable defaults.
[default_config]
M_iter = 1_000
N = 1_000
N_iter = 1_000
T = "300.0 kelvin"
alpha_factor = "0.25 halfturn"
bin_width = "1.0 kelvin"
dc = "0.0005 meter"
energy_max = "2.0e5 kelvin"
energy_max_rate = "1.0e5 kelvin"
lengths = [ [ 0.001, 0.00244, 0.101, 0.00448, 0.0005 ], "meter" ]
pressures = [ [ 194.0, 3.88 ], "pascal"]
resolution = 1_000
tolerance = 1e-8
voltages = [ [ -19, -9, -7, -6, 11 ], "volt" ]
[default_config.gas]
radius = "1.84e-10 meter"
mass = "4.65e-26 kilogram"
adiabatic_index = 1.4
[[configs]]
name = "simple"
[[configs]]
name = "with-quadrupole-and-pinhole"
radius_pinhole = "1 mm"
[configs.quadrupole]
dc_field = "0.0 volt"
ac_field = "200.0 volt"
radiofrequency = "1.3e6 Hz"
r_quadrupole = "6.0e-3 meter"
Usage:
Options:
-t, --db-type [experiment|cluster|super]
The type of database to create: this will
determine which tables are created
-a, --ase Create a linked ASE database
-w, --warm Warm the database with histogrammed data
--help Show this message and exit.
apitofsim db refresh-views
Refresh views in the database at path DATABASE (please ignore)
Usage:
Options:
apitofsim db report
Produce a report REPORT_TYPE from the database at path DATABASE and write it to CSV at path CSVOUT.
All databases have the following reports * The cluster-report contains one row per parent cluster. * The pathway-report contains the input pathways giving one row per pathway, with no information about results.
Databases created as --db-type=experiment additionally have the following reports: * The experiment-pathway-report contains one row per pathway / experiment run, and includes the outcome of that run for that pathway. * The experiment-cluster-report per parent cluster / experiment run, and includes the summarises information results from its pathways. * The experiment-summary contains one row per experiment run, and summarizes the outcomes across all pathways for that run. * The spectrogram report contains the same data used to plot spectograms.
Usage:
apitofsim db report [OPTIONS] [[cluster-report|pathway-report|experiment-
pathway-report|experiment-cluster-report|experiment-
summary|spectrogram]] DATABASE CSVOUT
Options:
apitofsim db run
Run simulation according to the configurations in DATABASE.
Usage:
Options:
--strict-dos / --no-strict-dos Whether to fail early when particle energy
go above the max energy the DOS is
histogrammed for
--filter-parent TEXT Only run pathways with a specified common
name for the parent cluster
--filter-pathway TEXT Only run the pathway specified using common
names as 'PARENT,CHILD,CHILD'
--filter-config TEXT Only run the experiment using the parameters
in the named configuration
--pathway-at-a-time Run one pathway at a time
--verbose
--help Show this message and exit.
apitofsim generate
Commands to inspect different files
Usage:
Options:
Subcommands
- pathways: No description was provided with this command.
apitofsim generate pathways
Usage:
Options:
apitofsim inspect
Commands to inspect different files
Usage:
Options:
Subcommands
- qc-log: Inspect a log file from a QC processing program such as Gaussian or ORCA
apitofsim inspect qc-log
Inspect a log file from a QC processing program such as Gaussian or ORCA
Usage:
Options:
The legacy tools
These tools are not recommended for new users, and kept available to support existing workflows.
If you have installed via Conda, and activated the relevant environment, the legacy command line tools apitofsim-skimmer, apitofsim-densityandrate and apitofsim-mass-spec should be installed and in your path.
If you have compiled the sources yourself, you will need to add build/src to your path for the following example to work.
An example is then available at examples/legacy_cli.
First cd to that directory, and then follow the instructions in the README.md file, included below:
You can run the included example pathway like so:
apitofsim-skimmer < inputs/config.in
apitofsim-densityandrate < inputs/config.in
apitofsim-mass-spec < inputs/config.in
Or using rus.sh.
Outputs are generated in work/out directory.