Skip to content

Command line interface

Jump to bottom
Peter Spackman edited this page Nov 9, 2023 · 2 revisions

occ uses CLI11 to parse command line flags, and has corresponding subcommands for each of the following protocols:

Command Line Options for occ

Help Options

  • -h,--help: Display a help message with the list of all available options and exit the program.
  • --help-all: Show help for all subcommands, including options and positional arguments for each.

Configuration and Execution Options

  • --config [occ_input.toml]: Read configuration from the specified ini or TOML file to set up the occ execution environment. Replace [occ_input.toml] with the path to your configuration file. Note that if this file exists it will be read, so you may wish to call it something else if you don't intend on having those settings always read for your current work.
  • --threads [1]: Set the number of threads for parallel execution. Default is 1.
  • --verbosity [2]: Set the logging verbosity level where {0=silent,1=minimal,2=normal,3=verbose,4=debug}. Default is 2.

CLI11 Configuration File Example

# occ_input.toml
threads = 4 # Number of threads
verbosity = 3 # Verbosity level

This occ_input.toml file sets occ to run with 4 threads and verbosity level 3 (verbose).

Molecular SCF calculations

For further details, please look over the tutorial which has concrete examples.

Positionals:

input: Path to the input file containing molecular geometry and other relevant data.
method_name: Name of the quantum chemistry method to use for the SCF calculation.
basis_name: Name of the basis set for the SCF calculation.

Options:

  • --geometry-filename: Path to the file containing molecular geometry. This is required and the same as the input option, just useful for input files.
  • --method: Specify the method name for the calculation.
  • --basis: Specify the basis set name.
  • --charge: Define the system net charge.
  • --multiplicity: Define the system multiplicity.
  • --unrestricted: Flag to use unrestricted SCF.
  • --dft-grid-*: Specify DFT integration grid parameters.
  • --df-basis: Define the basis set for density fitting.
  • --spherical: Flag to use spherical harmonics for the basis set.
  • --point-charges: Path to the file listing point charges.
  • --solvent: Name of the solvent for implicit solvation models.
  • --solvent-file: Path to the file to write solvent surface information.
  • --xdm: Use XDM dispersion correction with parameters --xdm-a1 and --xdm-a2.

Configuration file example for scf

Note that these aren't suggested settings, just an example.

# scf_section.toml
[scf]
input = "molecule.xyz" # or geometry_filename = "molecule.xyz"
method = "B3LYP"
basis = "def2-tzvp"
charge = -1
multiplicity = 2
unrestricted = true
dft_grid_max_angular = 590
dft_grid_min_angular = 50
dft_grid_radial_precision = 1e-5
dft_grid_reduce_light_elements = false
df_basis = "def2-universal-jkfit"
spherical = true
point-charges = "charges.txt"
solvent = "water"
solvent-file = "solvent.surface"
xdm = true
xdm_a1 = 0.500
xdm_a2 = 1.500

CE model pair energies

For further details, please look over the tutorial which has concrete examples.

Use the pair subcommand to compute the pair energy between two monomers. Due to the complex nature of rotation and translation specifications, it is highly recommended to provide these values through a configuration file.

Options:

  • -m,--model: Specify the energy model to use for the calculation.
  • -a,--monomer_a: Path to the wavefunction source file for monomer A. This is required.
  • -b,--monomer_b: Path to the wavefunction source file for monomer B. This is required.
  • --rotation-a: Nine floating-point numbers defining the rotation matrix for monomer A in row-major order.
  • --rotation-b: Nine floating-point numbers defining the rotation matrix for monomer B in row-major order.
  • --translation-a: Three floating-point numbers defining the translation vector for monomer A.
  • --translation-b: Three floating-point numbers defining the translation vector for monomer B.
  • --json: Path to the output JSON file that will be written with calculation results.

Configuration file example for pair (recommended)

Due to the complexity of inputting rotation and translation matrices through the command line, it is strongly advised to use a configuration file for pair operations. Here is an example template for such a file:

# pair_config.toml
[pair]
model = "ce-b3lyp"
monomer_a = "monomer_a.fchk"
monomer_b = "monomer_b.json"
rotation_a = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
rotation_b = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
translation_a = [0.0, 0.0, 0.0]
translation_b = [0.0, 0.0, 0.0]
json = "output.json"

In the configuration file, replace the arrays for rotation_a, rotation_b, translation_a, and translation_b with the actual values corresponding to your monomers' orientations and positions. Save this file as pair_config.toml and use the --config option to specify this file when running the pair subcommand.

Lattice/Cohesive energy calculations

The elat subcommand is used to compute the crystal lattice energy.

Positionals:

  • crystal: Path to the input crystal structure file in CIF format. This is required for lattice energy computation.

Options:

  • -m,--model: Specify the energy model to use for calculation.
  • --json: Specify the JSON output filename.
  • -r,--radius: Define the maximum radius in Angstroms to consider for neighbors.
  • --radius-increment: Set the step size in Angstroms for the direct space summation increment.
  • -w,--wolf: Use the Wolf method to accelerate convergence.
  • --crystal-polarization: Calculate the polarization term using the full crystal electric field.

Configuration file example for elat

Given the detailed nature of the elat command's options, a configuration file is not only convenient but can prevent errors associated with manual entry. Below is an example of what the configuration might look like in TOML format:

# elat_config.toml
[elat]
model = "ce-1p"
crystal = "crystal_structure.cif"
json = "output.json"
radius = 12.0
radius_increment = 3.8
wolf = true
crystal_polarization = true

The above configuration should be adjusted according to your specific requirements, with the correct path to your CIF file and the desired parameters for your calculation. Save this configuration as e.g. elat_config.toml and pass it to the elat subcommand using the --config option.

Crystal Growth energy calculations

The cg subcommand calculates crystal growth free energies.

Positionals:

  • input: The path to the input Crystallographic Information File (CIF) that describes the crystal structure for which the growth free energy is to be calculated.

Options:

  • -r,--radius: Specify the maximum search radius for neighboring particles in Angstroms. This defines the extent of the local environment considered during the crystal growth calculation.
  • -m,--model: Define the energy model used for calculating interactions within the crystal structure.
  • -c,--cg-radius: Set the maximum radius for nearest neighbors in the crystal growth (CG) file, which must be less than or equal to the value specified for --radius.
  • -s,--solvent: Name of the solvent used in the system, which can affect the crystal growth process.
  • --charges: Provide the net charge of the system, which can be important for calculating electrostatic interactions.
  • -w,--wavefunction-choice: Specify the choice of wavefunctions that influence the calculation of electronic properties during crystal growth.
  • --write-kmcpp: Output an input file compatible with the kmcpp program, which can be used for further analysis or simulation.
  • --xtb: Utilize the xtb (extended tight-binding) method for approximating interaction energies, beneficial for complex systems.
  • -d,--dump: Enable the writing of dump files that contain detailed state information of the growth process for subsequent review or debugging.
  • --atomic: Indicate that the crystal is atomic, meaning that no bonds will be considered in the growth model, which simplifies the calculation.
  • --surface-energies: Calculate and output surface energies. The argument specifies how many surface energies to calculate and can trigger the writing of .gmf morphology files.
  • --list-available-solvents: List all solvents that can be used within the cg subcommand and exit the program.

Molecular Isosurfaces

The isosurface command is used to compute molecular isosurfaces which can be useful for visualizing electron density or Hirshfeld surfaces. The command requires specifying the geometry of the molecule in an input file, along with an optional environment geometry file.

Positional Arguments:

  • geometry: This is the input geometry file for the molecule in XYZ format that defines the positions of the atoms in the molecule.
  • environment: The environment geometry file in XYZ format, which is optional and specifies the geometry of the surrounding environment.

Options:

  • --max-depth: Specifies the maximum voxel depth for the isosurface calculation. Voxel depth determines the resolution of the isosurface.
  • --separation: This option sets the target voxel separation in the isosurface grid.
  • --isovalue: This value defines the isosurface value to be used in the calculation, which can correspond to a specific electron density value.
  • --background-density: When set, this option adds a background density to the isosurface to close off the surface and can be used for better visualization or to fill in surface gaps.

Example Configuration File for isosurface 

[isosurface]
geometry = "molecule.xyz"
environment = "environment.xyz"
max_depth = 6
separation = 0.2
isovalue = 0.002
background_density = 0.000001

Clone this wiki locally