Command-Line Interface¶

qm-atlas ships a single executable, qm-atlas, that dispatches to a set of subcommands. Running it without arguments prints an overview of the available commands:

qm-atlas

The `pipeline` command¶

The main entry point for multi-step workflows is the pipeline command. It chains several calculation steps into a single workflow that is fully described in a .yaml configuration file:

qm-atlas pipeline --config my_workflow.yaml \
    --input_file+ ./molecules.sdf \
    --results_directory ./results

The config file lists the steps to run, in order, together with the options for each step. This lets you specify complex calculations — for example “read input, generate conformers, optimize them, then compute COSMOtherm properties” — entirely in one place and reproduce them from a single command. Steps that submit jobs to a cluster automatically block subsequent steps until they finish, and the whole pipeline can itself be submitted to the cluster.

Step commands¶

Each step that the pipeline runs is also a standalone subcommand, and each of them can be called directly. This is useful for running or re-running a single stage of a workflow. The available step commands include:

Command	Description
`read_input`	Read input molecules and create compound directories.
`add_reference_conformers`	Register reference conformers in compound directories.
`fast_conformers`	Run the fast conformer-generation workflow.
`rescoss_conformers`	Run the ReSCoSS conformer-generation workflow.
`optimize_reference_conformers`	Constrained optimization of reference conformers.
`conformer_properties`	Calculate conformer-based QM properties (Fukui, NMR, …).
`cosmotherm_properties`	Calculate COSMOtherm properties (logP, ΔG_solv, …).
`cosmo_pka`	Calculate pKa values with COSMOtherm.
`generate_tautomers`	Generate tautomers and register them as new states.
`protonate`	Generate protonation states and register them as new states.
`solvent_screening`	COSMOtherm pure-solvent and mixture solubility screening.
`cocrystal_screening`	COSMOtherm co-crystal screening.
`calculate_boltzmann_weights`	Per-conformer Boltzmann weights from a calculated energy property.
`aggregate_conformer_properties`	Aggregate per-conformer properties into per-state values.
`collect`	Collect results into a single directory.

Getting help¶

Every command accepts --help to print its own options:

qm-atlas --help                 # global options and command list
qm-atlas pipeline --help        # options for the pipeline command
qm-atlas fast_conformers --help # options for an individual step

Skipping already-computed work¶

Several step commands check for existing results before running and skip worker paths that are already complete, so re-running a command (or resuming an interrupted run) only does the remaining work. As a consequence, a command may do nothing, or only part of the work, when results are already present.

Command	When a worker path is skipped
`fast_conformers`	The compound already has generated conformers.
`rescoss_conformers`	The compound already has generated conformers.
`optimize_reference_conformers`	Every requested constrained-optimization setting is already present for the reference conformer. Adding a new setting (e.g. a new force constant) reruns only that setting.
`conformer_properties`	The conformer already carries every SDF property tag the configured calculation tasks would write.

Pass --force_rerun to bypass these checks and recompute everything:

qm-atlas conformer_properties --config props.yaml \
    --results_directory ./results --force_rerun

Discovering options with `describe`¶

Many step commands dispatch to interchangeable backends — different property calculators, geometry optimizers, or conformer generators — each with their own options. The describe command lists these backends and their configurable options so you know what to put in a config file:

qm-atlas describe                          # list all option categories
qm-atlas describe calculators              # list available property calculators
qm-atlas describe calculators xtb_single_point   # options for one calculator
qm-atlas describe optimizers jobex         # options for one optimizer

Checking the software environment (`test_software`)¶

test_software is a standalone utility command — it is not a workflow step and plays no part in the pipeline. It runs the wrapper self-tests that ship with the installed package against a software configuration, so you can verify that the configured external programs actually work:

qm-atlas test_software --software_config /path/to/software_config.yaml
qm-atlas test_software    # uses QM_ATLAS_SOFTWARE_CONFIG_FILE / defaults

Programs disabled in the configuration are skipped; enabled ones are exercised against the real binaries. The exit code is the pass/fail signal (useful for CI), --report results.xml writes a JUnit report, and any extra arguments are forwarded to pytest (e.g. -k turbomole to check a single backend). See Software Configuration for how program availability is determined.

Global options¶

The following options apply to any command:

Option	Description
`--debug`	Set logging to debug level.
`--silent`	Set logging to error-only level.
`--version`	Print the version and exit.
`--software_config`	Path to a software configuration YAML file (overrides the `QM_ATLAS_SOFTWARE_CONFIG_FILE` environment variable). See Software Configuration.

Example pipelines¶

The cli_examples/ directory in the repository contains ready-to-run pipeline configurations that illustrate common end-to-end workflows. Each file documents, in its header comment, what the pipeline does and how to invoke it — copy one as a starting point and adapt it to your needs.

Example	Description
`cli_examples/mini_strain.yaml`	Minimal strain-energy estimate that runs entirely on the local machine: A small conformer ensemble based on rdkit’s ETKDGv3, and xtb-based energies.
`cli_examples/fast_strain.yaml`	Strain energy using the fast conformer ensemble as the reference, with g-xtb energies and cluster submission.
`cli_examples/rescoss_strain.yaml`	Strain energy using the ReSCoSS conformer ensemble and COSMOtherm energies as the reference.
`cli_examples/rescoss_properties.yaml`	ReSCoSS conformer generation followed by COSMOtherm property calculations (logP, ΔG_solv, descriptors, PSA).
`cli_examples/complex_properties.yaml`	Multi-property pipeline: ReSCoSS + COSMO properties, Turbomole Fukui and NMR shieldings, a Jaguar calculation run on only the lowest-energy conformer, and Boltzmann-weighted aggregation. See Running an expensive calculation on a single conformer.
`cli_examples/cocrystal_screening.yaml`	Standalone co-crystal screening on the `.cosmo` files in an existing results directory. See Screening an existing results directory.
`cli_examples/solvent_screening.yaml`	Standalone solvent (solubility) screening on the `.cosmo` files in an existing results directory. See Screening an existing results directory.

All examples are run the same way — point --config at the file and inject the input and output paths on the command line. The strain pipelines additionally take a --reference_input_file with the reference conformers:

qm-atlas pipeline --config cli_examples/rescoss_strain.yaml \
    --input_file+ ./molecules.sdf \
    --reference_input_file+ ./reference_conformers.sdf \
    --results_directory ./results

The rescoss_strain example in full:

cli_examples/rescoss_strain.yaml¶

## Pipeline for a strain energy calculation at COSMO-FINE level.
## The strain energy is estimated as the minimum energy difference between
## the optimized reference conformers whose Optimization_RMSD is below 0.3,
## and the lowest-energy conformer found in the ReSCoSS conformer ensemble.
## The constraint on the Optimization_RMSD is to ensure that the conformation
## does not move too far from the original reference in the constrained optimization.
## If the constrained optimization leads to higher optimization RMSD values,
## consider changing the force constants in the constrained optimization.
## After the QM/COSMO calculations, calculate_boltzmann_weights computes each
## conformer's energy difference to the lowest-energy conformer.
## A final aggregate_conformer_properties step then takes the minimum of that
## energy difference over the optimized reference conformers whose
## Optimization_RMSD is below 0.3.
##
## To run this pipeline, you can use the following command, which injects
## the necessary input and results directories:
##
##   qm-atlas pipeline --config rescoss_strain.yaml \
##      --input_file+ <SDF file with compounds> \
##      --reference_input_file+ <SDF file with reference conformers> \
##      --results_directory <directory to store results>

steps:
  - command: read_input

  - command: rescoss_conformers
    submission_config:
      submit: true

  - command: add_reference_conformers

  - command: optimize_reference_conformers
    submission_config:
      submit: true
      cores_per_task: 2
      max_time: 1day
    ## Two force constants are used here. You can inspect the results to understand
    ## whether the answer depends on how tightly the pose was held.
    constrained_optimization_config:
      - - backend: xtb_turbomole
          constrain: True
          force_constant: 0.5
      - - backend: xtb_turbomole
          constrain: True
          force_constant: 0.1

  - command: conformer_properties
    submission_config:
      submit: true
    conformer_property_options:
      calculation_tasks:
        - backend: "turbomole_single_point"
          basis: def2-TZVPD
          functional:
            - b-p
          use_cosmo: true

  - command: cosmotherm_properties
    submission_config:
      submit: true
    cosmo_property_options:
      calculation_tasks:
        - backend: "cosmo_descriptors"
          solvent_name: "water"

  #    Calculate each conformer's energy difference to the lowest-energy
  #    conformer of its state, from the cosmotherm energy (in kcal/mol).
  #    The result is written per conformer as the "relative_energy" property.
  - command: calculate_boltzmann_weights
    boltzmann_options:
      energy_property: "cosmo_water_E_COSMO+dE+Mu"
      energy_unit: "kcal/mol"
      relative_energy_property: "relative_energy"
      relative_energy_unit: "kcal/mol"

  #    Strain estimate: over the optimized reference conformers only, take the
  #    minimum energy difference among those whose Optimization_RMSD is < 0.3.
  #    The result is written per state as "relative_energy_min".
  - command: aggregate_conformer_properties
    aggregate_options:
      selection:
        source: reference_results
        property_filters:
          - property_name: "Optimization_RMSD"
            max_value: 0.30
      properties:
        - property_name: relative_energy
          property_type: scalar
          operations:
            - operation: min

  #    Overlay each state's result conformers onto the registered reference input
  - command: align
    align_options:
      reference:
        mode: reference_input
      alignment:
        backend: rdkit
      rmsd_property: alignment_rmsd

Running an expensive calculation on a single conformer¶

cli_examples/complex_properties.yaml is a larger pipeline that layers several property calculations on top of the ReSCoSS + COSMO workflow: Turbomole Fukui indices and NMR shieldings for every conformer, a Jaguar hydrogen-abstraction calculation, and a final Boltzmann-weighted aggregation.

Its main point is a common cost-saving pattern: run an expensive method on only the single most relevant conformer instead of on the whole ensemble. Each conformer_properties step accepts a conformer_selection block that filters the result conformers before the calculation runs. Using keep_lowest: 1 on a per-conformer energy keeps just the global-minimum conformer — here ranked by the COSMO-RS energy written earlier by the cosmotherm_properties step:

- command: conformer_properties
  conformer_selection:
    property_filters:
      - property_name: "cosmo_water_E_COSMO+dE+Mu"
        keep_lowest: 1
  conformer_property_options:
    calculation_tasks:
      - backend: "jaguar_h_abstraction_energies"

The same conformer_selection mechanism accepts energy windows, absolute bounds, and reference-only sources (see ConformerSelection), so it can just as easily restrict a calculation to, say, every conformer within 2 kcal/mol of the minimum.

The pipeline finishes by computing per-conformer Boltzmann weights from the same COSMO-RS energy and taking Boltzmann-weighted averages of the per-atom Fukui and NMR properties in an aggregate_conformer_properties step.

The complex_properties example in full:

cli_examples/property_calculation_workflow.yaml¶

## Complex multi-property pipeline.
##
## This pipeline combines the usual ReSCoSS + COSMO property workflow with
## several additional QM properties, and shows how to run an expensive
## calculation on a single conformer instead of on the whole ensemble.
##
## Overview of the steps:
##   1. read_input                — create the compound directories.
##   2. rescoss_conformers        — generate the ReSCoSS conformer ensemble.
##   3. conformer_properties      — COSMO-FINE single points (BP/def2-TZVPD with
##                                  COSMO) that write the .cosmo files. We also
##                                  calculate Turbomole Fukui indices and NMR shieldings
##                                  for every conformer in this step.
##   4. cosmotherm_properties     — commonly used COSMO-RS properties (logP, ΔG_solv,
##                                  per-conformer descriptors/energies, PSA).
##   5. conformer_properties      — Jaguar hydrogen-abstraction energies, run
##                                  ONLY on the single lowest-energy conformer
##                                  (ranked by the COSMO-RS energy from step 4).
##                                  The expensive method is
##                                  applied to one representative conformer rather
##                                  than the whole ensemble.
##   6. calculate_boltzmann_weights — per-conformer Boltzmann weights from the
##                                  COSMO-RS energies.
##   7. aggregate_conformer_properties — Boltzmann-weighted averages of the
##                                  per-conformer properties (Fukui, NMR).
##
## To run this pipeline, you can use the following command, which injects the
## input file and results directory:
##
##   qm-atlas pipeline --config complex_properties.yaml \
##      --input_file+ <SDF file with compounds> \
##      --results_directory <directory to store results> \
##      --submission_config.submit true
##       # submits the pipeline monitoring job to the cluster.

steps:
  - command: read_input

  - command: rescoss_conformers
    # generation of ReSCoSS conformers using default options.
    submission_config:
      submit: true

  - command: conformer_properties
    # COSMO-FINE single points (BP/def2-TZVPD with COSMO) that write the .cosmo
    # files consumed by the cosmotherm_properties step below.
    submission_config:
      submit: true
    conformer_property_options:
      calculation_tasks:
        - backend: "turbomole_single_point"
          basis: def2-TZVPD
          functional:
            - b-p
          use_cosmo: true
        - backend: "turbomole_fukui_indices"
          basis: def2-TZVP
          functional:
            - pbe
        - backend: "turbomole_nmr_shielding"
          basis: def2-TZVP

  - command: cosmotherm_properties
    # the usual COSMO-RS properties calculated from the .cosmo files. The
    # cosmo_descriptors task writes a per-conformer COSMO-RS energy
    # ("cosmo_water_E_COSMO+dE+Mu") that is reused for conformer ranking and
    # Boltzmann weighting further down.
    submission_config:
      submit: true
    cosmo_property_options:
      calculation_tasks:
        - backend: "cosmo_logp"
        - backend: "cosmo_delta_g"
          solvent_name: "water"
        - backend: "cosmo_descriptors"
          solvent_name: "water"
        - backend: "cosmo_psa"

  - command: conformer_properties
    # expensive Jaguar hydrogen-abstraction energies, run on ONLY the single
    # lowest-energy conformer. conformer_selection filters the result conformers
    # before the calculation: keep_lowest=1 on the COSMO-RS energy keeps just the
    # global-minimum conformer, so the costly method is not repeated across the
    # whole ensemble.
    submission_config:
      submit: true
      cores_per_task: 4
    conformer_selection:
      property_filters:
        - property_name: "cosmo_water_E_COSMO+dE+Mu"
          keep_lowest: 1
    conformer_property_options:
      calculation_tasks:
        - backend: "jaguar_h_abstraction_energies"
          atom_idcs: "C" # run on all carbon atoms, which have hydrogens attached.
          # The Jaguar wrapper will automatically find the attached H.
          property_prefix: "jaguar_h_abstraction"

  - command: calculate_boltzmann_weights
    # per-conformer Boltzmann weights from the COSMO-RS energies (in kcal/mol),
    # written to the "boltzmann_weight" property for use in the aggregation step.
    boltzmann_options:
      energy_property: "cosmo_water_E_COSMO+dE+Mu"
      energy_unit: "kcal/mol"
      weight_property: "boltzmann_weight"

  - command: aggregate_conformer_properties
    # Boltzmann-weighted averages of the per-conformer properties over the whole
    # ensemble. Fukui indices and NMR shieldings are per-atom properties, so they
    # are aggregated element-wise per atom.
    #
    # representative_structure (off by default) additionally writes one SDF per
    # state ("{state}_representative.sdf") into the compound directory. It carries
    # the geometry of the lowest-energy conformer (selected here via keep_lowest=1
    # on the COSMO-RS energy) with the aggregated properties stamped onto it. The
    # atom-based averages become per-atom SDF properties, so RDKit re-parses them
    # onto the atoms on load — a convenient, self-contained representation of the
    # ensemble-averaged per-atom values. The file is not registered as a result
    # conformer, so it does not feed back into selection or aggregation.
    aggregate_options:
      representative_structure:
        enabled: true
        geometry_selection:
          property_filters:
            - property_name: "cosmo_water_E_COSMO+dE+Mu"
              keep_lowest: 1
      properties:
        - property_name: "tm_fukui_fukui_electrophilic_mulliken"
          property_type: atom_based
          operations:
            - operation: boltzmann_mean
              weight_property: "boltzmann_weight"
        - property_name: "tm_fukui_fukui_nucleophilic_mulliken"
          property_type: atom_based
          operations:
            - operation: boltzmann_mean
              weight_property: "boltzmann_weight"
        - property_name: "tm_nmr_shieldings_isotropic"
          property_type: atom_based
          operations:
            - operation: boltzmann_mean
              weight_property: "boltzmann_weight"

Screening an existing results directory¶

The co-crystal and solvent screenings both operate on .cosmo files that were generated earlier — for example by the conformer_properties step of cli_examples/rescoss_properties.yaml, which writes COSMO-FINE .cosmo files for every conformer. Rather than re-running the whole pipeline, the two screening steps can be run as standalone commands against the results directory that already contains those files.

Because these are standalone commands (not pipeline steps), the results directory is injected through --input.results_directory instead of --results_directory:

qm-atlas cocrystal_screening \
    --config cli_examples/cocrystal_screening.yaml \
    --input.results_directory ./results

qm-atlas solvent_screening \
    --config cli_examples/solvent_screening.yaml \
    --input.results_directory ./results

cli_examples/cocrystal_screening.yaml¶

## Standalone co-crystal screening on an existing results directory.
##
## This config runs a COSMOtherm co-crystal screening on the .cosmo files that
## are already present in a results directory (e.g. one produced by the
## `rescoss_properties.yaml` pipeline, whose `conformer_properties` step writes
## COSMO-FINE .cosmo files for every conformer).
##
## Run it by pointing --config at this file and injecting the results directory
## that holds the compound sub-directories with the .cosmo files:
##
##   qm-atlas cocrystal_screening \
##      --config cli_examples/cocrystal_screening.yaml \
##      --input.results_directory <directory with .cosmo files>
##
## Set --submission_config.submit to control whether the job is submitted to the
## cluster (below) or run locally.

command: cocrystal_screening

submission_config:
  submit: true

cocrystal_screening_options:
  # coformer names must match .cosmo files in the cosmotherm database, or in an
  # additional directory provided via coformers_dirs.
  coformers:
    - adenine
    - ammonia
    - arginine
  stoichiometry: [1, 1]
  # Additional directories searched for coformer .cosmo files (in addition to
  # the COSMOtherm database) can be added. Each coformer name above is resolved to
  # a file named "<name>_c0.cosmo" in these directories, e.g. "adenine_c0.cosmo".
  # Set it here, or inject it on the command line:
  #
  #   --cocrystal_screening_options.coformers_dirs+ <directory with .cosmo files>
  #
  # coformers_dirs:
  #   - <directory with coformer .cosmo files>

cli_examples/solvent_screening.yaml¶

## Standalone solvent (solubility) screening on an existing results directory.
##
## This config runs a COSMOtherm solubility screening on the .cosmo files that
## are already present in a results directory (e.g. one produced by the
## `rescoss_properties.yaml` pipeline, whose `conformer_properties` step writes
## COSMO-FINE .cosmo files for every conformer).
##
## Run it by pointing --config at this file and injecting the results directory
## that holds the compound sub-directories with the .cosmo files:
##
##   qm-atlas solvent_screening \
##      --config cli_examples/solvent_screening.yaml \
##      --input.results_directory <directory with .cosmo files>
##
## To anchor the screening to measured reference solubilities, layer a second
## config file on top (see references.yaml); the later --config is deep-merged
## over this one:
##
##   qm-atlas solvent_screening \
##      --config cli_examples/solvent_screening.yaml \
##      --config cli_examples/references.yaml \
##      --input.results_directory <directory with .cosmo files>

command: solvent_screening

submission_config:
  submit: true

solvent_screening_options:
  # binary solubility screening over all pairs of the four solvents.
  solvent_combinations:
    - [water, methanol]
    - [water, ethanol]
    - [water, acetone]
    - [methanol, ethanol]
    - [methanol, acetone]
    - [ethanol, acetone]

Combining a base config with reference solubilities¶

Reference solubilities anchor the solvent screening to measured values, turning COSMOtherm’s relative screening into an absolute (iterative) one. Because they change from compound to compound, it is convenient to keep the base screening definition fixed and supply the references separately.

The --config option can be given more than once: each additional file is deep-merged over the previous ones. This lets you keep a standard solvent_screening.yaml and layer a small references.yaml on top without editing the base file:

qm-atlas solvent_screening \
    --config cli_examples/solvent_screening.yaml \
    --config cli_examples/references.yaml \
    --input.results_directory ./results

The references list from the second file is injected into the solvent_screening_options of the first, leaving everything else untouched:

cli_examples/references.yaml¶

## Reference solubilities for the solvent screening.
##
## This file is meant to be layered on top of `solvent_screening.yaml` via a
## second --config argument. jsonargparse deep-merges the two files, so the
## `references` list defined here is injected into the `solvent_screening_options`
## from the base config while leaving everything else untouched:
##
##   qm-atlas solvent_screening \
##      --config cli_examples/solvent_screening.yaml \
##      --config cli_examples/references.yaml \
##      --input.results_directory <directory with .cosmo files>
##
## Providing references switches COSMOtherm from a "relative" screening to an
## "absolute" one anchored to these measured values. Keeping this file
## separate allows the reference solubilities to be edited per compound without
## touching the base screening definition.

solvent_screening_options:
  references:
    # made-up reference solubilities (cosmotherm unit 'gl' = gram solute per
    # liter solution) at 25 °C. Check the cosmotherm manual for an overview of
    # the available solubility units.
    - value: 5.4
      solvent_names: [acetone]
      solubility_unit: gl
      temperature: 25.0
    - value: 2.4
      solvent_names: [methanol]
      solubility_unit: gl
      temperature: 25.0

Note

Merging additional --config files works for standalone commands like solvent_screening because references lives at the top level of the command’s options. It cannot be used to inject references into a pipeline config, where the screening options are nested inside the steps list.