Skip to content

Parameters

Introduction

About

This section provides a detailed overview of all unique parameters for all workflows.

To identify the parameters allowed for a specific workflow, use the explore command or workflow.show_parameters():

simmate workflows explore

workflow.show_parameters()

File vs. Python formats

When switching from Python to YAML, make sure you adjust the input format of your parameters. This is especially important if you use python a list or dict for one of your input parameters. Further, if you have complex input parameters (e.g. nested lists, matricies, etc.), we recommend using a TOML input file instead:

# in python
my_parameter = [1,2,3]

# in yaml
my_parameter:
    - 1
    - 2
    - 3


# in python
my_parameter = {"a": 123, "b": 456, "c": ["apple", "orange", "grape"]}

# in yaml
my_parameter:
    a: 123
    b: 456
    c:
        - apple
        - orange
        - grape

# in toml
[my_parameter]
a = 123
b = 456
c = ["apple", "orange", "grape"]


# in python
my_parameter = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]

# in yaml (we recommend switching to TOML!)
my_parameter:
    - - 1
        - 2
        - 3
    - - 4
        - 5
        - 6
    - - 7
        - 8
        - 9

# in toml
my_parameter = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]


# in python
my_parameter = (1,2,3)

# in yaml
my_parameter:
    - 1
    - 2
    - 3
# WARNING: This will return a list! Make sure you call 
#   `tuple(my_parameter)`
# at the start of your workflow's `run_config` if you need a tuple.

# in toml
my_parameter = [1, 2, 3]
# WARNING: This will return a list! Make sure you call 
#   `tuple(my_parameter)`
# at the start of your workflow's `run_config` if you need a tuple.

algorithm

This parameter is specific to the BadELf workflows in the warrenapp. Options include badelf, voronelf, or zero-flux.

zero-flux will use traditional bader-like partitioning. voronelf will use planes located at minima in the ELF along atomic bonds. badelf will use a hybrid, separating atoms with planes and bare electrons with a zero-flux surface.

algorithm: badelf

algorithm = "badelf"

algorithm = "badelf"

angle_tolerance

This parameter is used to determine if the angles between sites are symmetrically equivalent when standardize_structure=True. The value is in degrees.

angle_tolerance: 10.0

angle_tolerance = 10.0

angle_tolerance = 10.0

chemical_system

This parameter specifies the chemical system to be used in the analysis. It should be given as a string in the format Element1-Element2-Element3-.... For example, Na-Cl, Y-C, and Y-C-F are valid chemical systems.

chemical_system: Na-Cl

chemical_system = "Na-Cl"

chemical_system = "Na-Cl"

Warning

Some workflows only accept a chemical system with a specific number of elements. An example of this is the structure-prediction.python.binary-composition search which only allows two elements (e.g. Y-C-F would raise an error)

command

This parameter specifies the command that will be called during the execution of a program. There is typically a default set for this that you only need to change if you'd like parallelization. For example, VASP workflows use vasp_std > vasp.out by default but you can override this to use mpirun.

command: mpirun -n 8 vasp_std > vasp.out

command = "mpirun -n 8 vasp_std > vasp.out"

command = "mpirun -n 8 vasp_std > vasp.out"

composition

The composition input can be anything compatible with the Composition toolkit class. Note that compositions are sensitive to atom counts / multiplicity. There is a difference between giving Ca2N and Ca4N2 in several workflows. Accepted inputs include:

a string (recommended)

composition: Ca2NF

composition = "Ca2NF"

composition = "Ca2NF"

a dictionary that gives the composition

composition:
    Ca: 2
    N: 1
    F: 1

[composition]
Ca = 2
N = 1
F = 1

composition={
    "Ca": 2, 
    "N": 1, 
    "F": 1,
}

a Composition object (best for advanced logic)

from simmate.toolkit import Compositon

composition = Composition("Ca2NF")

compress_output

This parameter determines whether to compress the directory to a zip file at the end of the run. After compression, it will also delete the directory. The default is False.

compress_output: true

compress_output = true

compress_output = True

copy_previous_directory

This parameter determines whether to copy the directory from the previous calculation (if one exists) and use it as a starting point for the new calculation. This is only possible if you provided an input that points to a previous calculation. For instance, structure would need to use a database-like input:

structure:
    database_table: Relaxation
    database_id: 123
copy_previous_directory: true

copy_previous_directory: true

[structure]
database_table = "Relaxation"
database_id = 123

structure = {"database_table": "Relaxation", "database_id": 123}
copy_previous_directory=True

diffusion_analysis_id

(advanced users only) This is the entry id from the DiffusionAnalysis table to link the results to. This is set automatically by higher-level workflows and rarely (if ever) set by the user.

directory

This is the directory where everything will be run -- either as a relative or full path. This is passed to the utilities function simmate.ulitities.get_directory, which generates a unique folder name if not provided (such as simmate-task-12390u243). This will be converted into a pathlib.Path object. Accepted inputs include:

leave as default (recommended)

a string

directory: my-new-folder-00

directory = "my-new-folder-00"

directory = "my-new-folder-00"

a pathlib.Path (best for advanced logic)

from pathlib import Path

directory = Path("my-new-folder-00")

directory_new

Exclusive to the restart.simmate.automatic workflow, this is the folder where the workflow will be continued. It follows the same rules/inputs as the directory parameter.

directory_old

Exclusive to the restart.simmate.automatic workflow, this is the original folder that should be used as the starting point. It follows the same rules/inputs as the directory parameter.

elf_analyzer_kwargs

Exclusive to BadELF workflows. These are the keyword arguments passed to the ElfAnalyzerToolkit class that control how features in the ELF (e.g. bare electrons, covalent/metallic bonds, etc.) are automatically found and labeled.

elf_analyzer_kwargs:
    resolution: 0.02,
    include_lone_pairs: false,
    include_shared_features: true,
    metal_depth_cutoff: 0.1,
    min_covalent_angle: 135,
    min_covalent_bond_ratio: 0.35,
    shell_depth: 0.05,
    electride_elf_min: 0.5,
    electride_depth_min: 0.2,
    electride_charge_min: 0.5,
    electride_volume_min: 10,
    electride_radius_min: 0.3,

[elf_analyzer_kwargs]
resolution = 0.02
include_lone_pairs = false
include_shared_features = true
metal_depth_cutoff = 0.1
min_covalent_angle = 135
min_covalent_bond_ratio = 0.35
shell_depth = 0.05
electride_elf_min = 0.5
electride_depth_min = 0.2
electride_charge_min = 0.5
electride_volume_min = 10
electride_radius_min = 0.3

elf_analyzer_kwargs = dict(
    resolution = 0.02,
    include_lone_pairs = false,
    include_shared_features = true,
    metal_depth_cutoff = 0.1,
    min_covalent_angle = 135,
    min_covalent_bond_ratio = 0.35,
    shell_depth = 0.05,
    electride_elf_min = 0.5,
    electride_depth_min = 0.2,
    electride_charge_min = 0.5,
    electride_volume_min = 10,
    electride_radius_min = 0.3,
)

Each keyword argument controls an aspect of how ELF features are found:

resolution

The interval at which to scan the ELF to generate BifurcationGraphs. Larger values will be faster, but may miss bifurcations.

include_lone_pairs

Whether or not to include lone-pairs in the labeled structure. It is generally recommended to leave this as false when using plane partitioning for atoms.

include_shared_features

Whether or not to include shared features such as metallic/covalent bonds in the labeled structure. If splitting these features at their maxima with planes is the desired output, set to false. If the goal is a comprehensive charge analysis of these features, set to true. If set to true, the shared_feature_algorithm parameter will control how they are separated from nearby atoms/features.

metal_depth_cutoff

For ELF features other than atom cores/shells or lone-pairs, this parameter controls the maximum depth (Difference from ELF maximum to bifurcation) that a metallic feature can have. Any non-atomic/lone-pair feature with a depth below this value will be assigned as metallic.

min_covalent_angle

For features other than atom cores/shells, the algorithm will check whether the feature is along an atomic bond within an angle tolerance. This corresponds to the angle between the neighboring atoms and the feature. Any feature with an angle below this value will not be assigned covalent.

min_covalent_bond_ratio

When determining between a lone-pair or covalent bond, the algorithm will check how far along the bond the feature is (noramalized to 1). Anything below this parameters value will be considered a lone-pair. This is done to avoid misassignment in situations where the lone-pairs align with nearby atoms in a dipole interaction.

shell_depth

In ionic compounds, the unshared electrons will form a sphere around the more electronegative atom. As the bond becomes more covalent, this feature will break into smaller features along the atomic bonds. As covalency increases, the depth of these features increases. Thus, this parameter effectively defines a cutoff for what should be considered covalent vs. ionic.

Additionally, due to voxelation, atomic shells may split into many different basins around their ELF maximum. This parameter also controls recombining these voxelated basins into one.

electride_elf_min

The minimum ELF value that a bare-electron feature must have to be considered an electride.

electride_depth_min

The minimum ELF depth that a bare-electron feature must have to be considered an electride.

electride_charge_min

The minimum charge that a bare-electron feature must have to be considered an electride.

electride_volume_min

The minimum volume that a bare-electron feature must have to be considered an electride.

electride_radius_min

The minimum ELF radius that a bare-electron feature must have to be considered an electride. The radius is defined as the distance from the feature to the closest atom minus that atoms radius. Atomic radii are determined by checking the EN difference between the atom and its nearest neighbors. If the EN difference is above 1.6, the average ionic radii for the atom is used. If the EN is below 1.6, the atomic radius is used.

find_electrides

Exclusive to the BadELF workflows. This parameter indicates whether the algorithm should search for electrides. Reasons to set this as false may be that the user knows there is no electride character in the structure of interest or if the user would like to manually indicate the location of electrides.

Warning

If this parameter is set to false, the labeled_structure_up and/or labeled_structure_down parameters must be set.

find_electrides: true

find_electrides = true

find_electrides = True

fitness_field

(advanced users only) For evolutionary searches, this is the value that should be optimized. Specifically, it should minimize this value (lower value = better fitness). The default is energy_per_atom, but you may want to set this to a custom column in a custom database table.

ignore_low_pseudopotentials

Exclusive to BadELF workflows. Indicates whether the algorithm should throw an exception when the used pseudopotential didn't contain enough valence electrons. It is generally recommended to leave this as False as the results will likely be nonsense. Instead it is recommended to use pseudopotentials with more electrons, such as Vasp's GW PPs.

ignore_low_pseudopotentials: false

ignore_low_pseudopotentials = false

ignore_low_pseudopotentials = False

input_parameters

(experimental feature) Exclusive to customized.vasp.user-config. This is a list of parameters to pass to workflow_base.

is_restart

(experimental feature) This parameter indicates whether the calculation is a restarted workflow run. The default is False. If set to true, the workflow will go through the given directory (which must be provided) and determine where to resume.

directory: my-old-calc-folder
is_restart: true

directory = "my-old-calc-folder"
is_restart = true

directory = "my-old-calc-folder"
is_restart = True

labeled_structure_up

In BadELF workflows, if find_electrides is set to false, this parameter is a structure with "dummy" atoms representing non-atomic features in the spin-up system. Inputs options are the same as for the structure parameter.

Note

If a non-polarized ELF/charge density is used, this represents the labeled structure for the total system.

The required labels for each type of non-atomic feature are:

Feature Label
Covalent Bond "Z"
Lone-Pair "Lp"
Metal "M"
Electride "E"
Other Bare Electron "Le" 
labeled_structure_up: Ca2N_labeled_up.cif

labeled_structure_up = Ca2N_labeled_up.cif

labeled_structure_up: "Ca2N_labeled_up.cif"

labeled_structure_down

The equivalent setting to labeled_structure_up for the spin-down system.

labeled_structure_down: Ca2N_labeled_down.cif

labeled_structure_down = Ca2N_labeled_down.cif

labeled_structure_down: "Ca2N_labeled_down.cif"

max_atoms

For workflows that involve generating a supercell or random structure, this will be the maximum number of sites to allow in the generated structure(s). For example, an evolutionary search may set this to 10 atoms to limit the compositions & stoichiometries that are explored.

max_atoms: 10

max_atoms = 10

max_atoms = 10

max_path_length

For diffusion workflows, this is the maximum length allowed for a single path.

max_path_length: 3.5

max_path_length = 3.5

max_path_length = 3.5

max_stoich_factor

This is the maximum stoichiometric ratio that will be analyzed. In a binary system evolutionary search, this will only look at non-reduced compositions up to the max_stoich_factor. For example, this means Ca2N and max factor of 4 would only look up to Ca8N4 and skip any compositions with more atoms (e.g. Ca10N5 is skipped)

max_stoich_factor: 5

max_stoich_factor = 5

max_stoich_factor = 5

max_supercell_atoms

For workflows that involve generating a supercell, this will be the maximum number of sites to allow in the generated structure(s). For example, NEB workflows would set this value to something like 100 atoms to limit their supercell image sizes.

max_supercell_atoms: 100

max_supercell_atoms = 100

max_supercell_atoms = 100

max_structures

For workflows that generate new structures (and potentially run calculations on them), this will be the maximum number of structures allowed. The workflow will end at this number of structures regardless of whether the calculation/search is converged or not.

max_structures: 100

max_structures = 100

max_structures = 100

migrating_specie

This is the atomic species/element that will be moving in the analysis (typically NEB or MD diffusion calculations). Note, oxidation states (e.g. "Ca2+") can be used, but this requires your input structure to be oxidation-state decorated as well.

migrating_specie: Li

migrating_specie = "Li"

migrating_specie = "Li"

migration_hop

(advanced users only) The atomic path that should be analyzed. Inputs are anything compatible with the MigrationHop class of the simmate.toolkit.diffusion module. This includes:

  • MigrationHop object
  • a database entry in the MigrationHop table

(TODO: if you'd like full examples, please ask our team to add them)

migration_images

The full set of images (including endpoint images) that should be analyzed. Inputs are anything compatible with the MigrationImages class of the simmate.toolkit.diffusion module, which is effectively a list of structure inputs. This includes:

MigrationImages object

a list of Structure objects

a list of filenames (cif or POSCAR)

migration_images:
    - image_01.cif
    - image_02.cif
    - image_03.cif
    - image_04.cif
    - image_05.cif

migration_images = [
    "image_01.cif",
    "image_02.cif",
    "image_03.cif",
    "image_04.cif",
    "image_05.cif",
]

migration_images = [
    "image_01.cif",
    "image_02.cif",
    "image_03.cif",
    "image_04.cif",
    "image_05.cif",
]

min_atoms

This is the opposite of max_atoms as this will be the minimum number of sites allowed in the generate structure(s). See max_atoms for details.

min_supercell_atoms

This is the opposite of max_supercell_atoms as this will be the minimum number of sites allowed in the generated supercell structure.

min_supercell_vector_lengths

When generating a supercell, this is the minimum length for each lattice vector of the generated cell (in Angstroms). For workflows such as NEB, larger is better but more computationally expensive.

min_supercell_vector_lengths: 7.5

min_supercell_vector_lengths = 7.5

min_supercell_vector_lengths = 7.5

nfirst_generation

For evolutionary searches, no mutations or "child" individuals will be scheduled until this number of individuals have been calculated. This ensures we have a good pool of candidates calculated before we start selecting parents and mutating them.

nfirst_generation: 15

nfirst_generation = 15

nfirst_generation = 15

nimages

The number of images (or structures) to use in the analysis. This does NOT include the endpoint images (start/end structures). More is better, but computationally expensive. We recommend keeping this value odd in order to ensure there is an image at the midpoint.

nimages: 5

nimages = 5

nimages = 5

Danger

For apps such as VASP, your command parameter must use a number of cores that is divisible by nimages. For example, nimages=3 and command="mpirun -n 10 vasp_std > vasp.out" will fail because 10 is not divisible by 3.

nsteadystate

This parameter sets the number of individual workflows to be scheduled at once, effectively setting the queue size of an evolutionary search. The number of workflows run in parallel is determined by the number of Workers started. However, the nsteadystate value sets the maximum number of parallel runs as the queue size will never exceed this value. This parameter is closely tied with steadystate_sources.

nsteadystate: 50

nsteadystate = 50

nsteadystate = 50

nsteps

This parameter sets the total number of steps for the calculation. For instance, in molecular dynamics workflows, the simulation will stop after this many steps.

nsteps: 10000

nsteps = 10000

nsteps = 10000

percolation_mode

This parameter sets the percolating type to detect. The default is ">1d", which searches for percolating paths up to the max_path_length. Alternatively, this can be set to "1d" to stop unique pathway finding when 1D percolation is achieved.

percolation_mode: 1d

percolation_mode = "1d"

percolation_mode = "1d"

relax_bulk

This parameter determines whether the bulk structure (typically the input structure) should be relaxed before running the rest of the workflow.

relax_bulk: false

relax_bulk: false

relax_bulk: false

relax_endpoints

This parameter determines whether the endpoint structures for an NEB diffusion pathway should be relaxed before running the rest of the workflow.

relax_endpoints: false

relax_endpoints: false

relax_endpoints: false

run_id

This parameter is the id assigned to a specific workflow run/calculation. If not provided, this will be randomly generated. It is highly recommended to leave this at the default value. This id is based on unique-ids (UUID), so every id should be 100% unique and in a string format.

run_id: my-unique-id-123

run_id = "my-unique-id-123"

run_id = "my-unique-id-123"

search_id

(advanced users only) This parameter is the evolutionary search that this individual is associated with. This allows us to determine which Selector, Validator, and StopCondition should be used when creating and evaluating the individual. When running a search, this is set automatically when submitting a new flow.

selector_kwargs

(advanced users only) This parameter is a dictionary of extra conditions to use when initializing the selector class. MySelector(**selector_kwargs). This is closely tied with the selector_name parameter.

selector_name

(experimental feature; advanced users only) This parameter is the base selector class that should be used. The class will be initialized using MySelector(**selector_kwargs). The input should be given as a string.

Warning

Currently, we only support truncated selection, so this should be left at its default value.

separate_spin

In BadELF workflows, determines whether the spin-up and spin-down ELF/charge-density should be treated separately. Setting to false more closely matches the original BadELF paper, but relies on the assumption that the system is closed and the spin-up/spin-down are identical.

separate_spin: true

separate_spin = true

separate_spin = True

shared_feature_algorithm

For BadELF workflows, this parameter determines how shared ELF features such as covalent/metallic bonds are seperated from nearby atoms. Options are "zero-flux" or "voronoi" corresponding to bader-like and plane-like seperations.

covalent_bond_alg: zero-flux

covalent_bond_alg = "zero-flux"

covalent_bond_alg = "zero-flux"

singleshot_sources

(experimental feature; advanced users only) This parameter is a list of structure sources that run once and never again. This includes generating input structures from known structures (from third-party databases), prototypes, or substituting known structures.

In the current version of simmate, these features are not enabled and this input should be ignored.

sleep_step

This parameter is the amount of time in seconds that the workflow will shutdown before restarting the cycle when there is a cycle within a workflow (such as iteratively checking the number of subworkflows submitted and updating results). For evolutionary searches, setting this to a larger value will save on computation resources and database load, so we recommend increasing it where possible.

run_id: 180

run_id = 180

sleep_step = 180  # 3 minutes

source

(experimental feature; advanced users only) This parameter indicates where the input data (and other parameters) came from. The source could be a number of things including a third party id, a structure from a different Simmate database table, a transformation of another structure, a creation method, or a custom submission by the user.

By default, this is a dictionary to account for the many different scenarios. Here are some examples of values used in this column:

# from a thirdparty database or separate table
source = {
    "database_table": "MatprojStructure",
    "database_id": "mp-123",
}

# from a random structure creator
source = {"creator": "PyXtalStructure"}

# from a templated structure creator (e.g. substituition or prototypes)
source = {
    "creator": "PrototypeStructure",
    "database_table": "AFLOWPrototypes",
    "id": 123,
}

# from a transformation
source = {
    "transformation": "MirrorMutation",
    "database_table":"MatprojStructure",
    "parent_ids": ["mp-12", "mp-34"],
}

Typically, the source is set automatically, and users do not need to update it.

standardize_structure

This parameter determines whether to standardize the structure during our setup(). This means running symmetry analysis on the structure to reduce the symmetry and convert it to some standardized form. There are three different forms to choose from and thus 3 different values that standardize_structure can be set to:

  • primitive: for the standard primitive unitcell
  • conventional: for the standard conventional unitcell
  • primitive-LLL: for the standard primitive unitcell that is then LLL-reduced
  • False: this is the default and will disable this feature

We recommend using primitive-LLL when the smallest possible and most cubic unitcell is desired.

We recommend using primitive when calculating band structures and ensuring we have a standardized high-symmetry path. Note,Existing band-structure workflows use this automatically.

To control the tolerances used to symmetrize the structure, you can use the symmetry_precision and angle_tolerance attributes.

By default, no standardization is applied.

standardize_structure: primitive-LLL

standardize_structure = "primitive-LLL"

standardize_structure = "primitive-LLL"

steadystate_source_id

(advanced users only) This parameter is the structure source that this individual is associated with. This allows us to determine how the new individual should be created. When running a search, this is set automatically when submitting a new flow.

steadystate_sources

(experimental feature; advanced users only) This parameter is a dictionary of sources that will be scheduled at a "steady-state", meaning there will always be a set number of individuals scheduled/running for this type of structure source. This should be defined as a dictionary where each is {"source_name": percent}. The percent determines the number of steady stage calculations that will be running for this at any given time. It will be a percent of the nsteadystate parameter, which sets the total number of individuals to be scheduled/running. For example, if nsteadystate=40 and we add a source of {"RandomSymStructure": 0.30, ...}, this means 0.25*40=10 randomly-created individuals will be running/submitted at all times. The source can be from either the toolkit.creator or toolkit.transformations modules.

singleshot_sources:
    RandomSymStructure: 0.30
    from_ase.Heredity: 0.30
    from_ase.SoftMutation: 0.10
    from_ase.MirrorMutation: 0.10
    from_ase.LatticeStrain: 0.05
    from_ase.RotationalMutation: 0.05
    from_ase.AtomicPermutation: 0.05
    from_ase.CoordinatePerturbation: 0.05

[singleshot_sources]
"RandomSymStructure": 0.30
"from_ase.Heredity": 0.30
"from_ase.SoftMutation": 0.10
"from_ase.MirrorMutation": 0.10
"from_ase.LatticeStrain": 0.05
"from_ase.RotationalMutation": 0.05
"from_ase.AtomicPermutation": 0.05
"from_ase.CoordinatePerturbation": 0.05

singleshot_sources = {
    "RandomSymStructure": 0.30,
    "from_ase.Heredity": 0.30,
    "from_ase.SoftMutation": 0.10,
    "from_ase.MirrorMutation": 0.10,
    "from_ase.LatticeStrain": 0.05,
    "from_ase.RotationalMutation": 0.05,
    "from_ase.AtomicPermutation": 0.05,
    "from_ase.CoordinatePerturbation": 0.05,
}

Note: if your percent values do not sum to 1, they will be rescaled. When calculating percent*nsteadystate, the value will be rounded to the nearest integer.

We are moving towards accepting kwargs or class objects as well, but this is not yet allowed. For example, anything other than percent would be treated as a kwarg:

[singleshot_sources.RandomSymStructure]
percent: 0.30
spacegroups_exclude: [1, 2, 3]
site_generation_method: "MyCustomMethod"

stop_conditions

(experimental feature; advanced users only) This parameter provides a set of stop conditions that will be checked periodically to determine if a FixedComposition evolutionary search should be stopped. It should be defined as a dictionary where each key is the string name of a StopCondition and the value is any kwargs that are needed to instantiate the class.

stop_conditions:
    BasicStopConditions:
        max_structures: 1000
        min_structures_exact: 100
        convergence_cutoff: 0.001
        best_survival_cutoff: 100
    ExpectedStructure:
        structure: NaCl.cif

[stop_conditions.BasicStopConditions]
max_structures = 1000
min_structures_exact = 100
convergence_cutoff = 0.001
best_survival_cutoff = 100
[stop_conditions.ExpectedStructure]
structure: NaCl.cif

stop_conditions = {
    "BasicStopConditions": {
    "max_structures": 1000,
    "min_structures_exact": 100,
    "convergence_cutoff": 0.001
    "best_survival_cutoff": 100
    },
    "ExpectedStructure": {
    "structure": "NaCl.cif"
    },
}

Currently, only the BasicStopConditions and ExpectedStructure stop conditions are supported. They each have the following subparameters

BasicStopConditions The BasicStopConditions are those that are important to all searches. If this StopCondition is not provided, defaults will be constructed.

max_structures

The maximum number of structures generated. The search will end at this number of structures regardless of if the search has converged. If not provided, the workflow estimates a reasonable value based on the number of atoms.

Warning

min_structure_exact takes priority over this setting, so it is possible for your search to exceed your maximum number of structures. If you want max_structures to have absolute control, you can set min_structure_exact to 0.

min_structures_exact

The minimum number of structures that must be calculated with exactly matching nsites as specified in fixed-composition. If not provided, the workflow estimates a reasonable value based on the number of atoms.

convergence_cutoff

The search will be considered converged when the best structure is not changing by this amount (in eV). In order to officially signal the end of the search, the best structure must survive within this convergence limit for a specific number of new individuals -- this is controlled by the best_survival_cutoff. The default of 1meV is typically sufficient and does not need to be changed. More often, users should update best_survival_cutoff instead.

best_survival_cutoff

The search will stop when the best individual remains unbeaten for this number of new individuals.

To account for similar structures (e.g., identical structures with minor energy differences), structures within the convergence_cutoff parameter (e.g., +1meV) are not considered when counting historical structures. This helps to prevent the search from continuing in cases where the search is likely already converged but making <0.1meV improvements. If not provided, the workflow estimates a reasonable value based on the number of atoms.

ExpectedStructure The ExpectedStructure stop condition will compare all structures generated in the search to a provided structure and immediately halt the search if there is a match.

expected_structure

When a structure is found in the search that matches this structure, the search will be stopped. The allowed inputs follow the same scheme as in the Structure parameter.

structure

The crystal structure to be used for the analysis. The input can be anything compatible with the Structure toolkit class. Accepted inputs include:

a filename (cif or poscar) (recommended)

structure: NaCl.cif

structure = NaCl.cif

structure="NaCl.cif"

a dictionary that points to a database entry. 

# example 1
structure:
    database_table: MatprojStructure
    database_id: mp-123

# example 2
structure:
    database_table: StaticEnergy
    database_id: 50

# example 3
structure:
    database_table: Relaxation
    database_id: 50
    structure_field: structure_final

# example 1
[structure]
database_table: MatprojStructure
database_id: mp-123

# example 2
[structure]
database_table: StaticEnergy
database_id: 50

# example 3
[structure]
database_table: Relaxation
database_id: 50
structure_field: structure_final

# example 1
structure={
    "database_table": "MatprojStructure",
    "database_id": "mp-123",
}

# example 2
structure={
    "database_table": "StaticEnergy",
    "database_id": 50,
}

# example 3
structure={
    "database_table": "Relaxation",
    "database_id": 50,
    "structure_field": "structure_final",
}

Note

instead of database_id, you can also use the run_id or directory to indicate which entry to load. Further, if the database table is linked to multiple structures (e.g. relaxations have a structure_start and structure_final), then you can also add the structure_field to specify which to choose.

a Structure object (best for advanced logic)

from simmate.toolkit import Structure

structure = Structure(
    lattice=[
        [2.846, 2.846, 0.000],
        [2.846, 0.000, 2.846],
        [0.000, 2.846, 2.846],
    ],
    species=["Na", "Cl"],
    coords=[
        [0.5, 0.5, 0.5],
        [0.0, 0.0, 0.0],
    ],
    coords_are_cartesian=False,
)

a Structure database object

structure = ExampleTable.objects.get(id=123)

json/dictionary serialization from pymatgen

subworkflow_kwargs

This parameter is a dictionary of parameters to pass to each subworkflow run. For example, the workflow will be ran as subworkflow.run(**subworkflow_kwargs). Note, many workflows that use this argument will automatically pass information that is unique to each call (such as structure).

subworkflow_kwargs:
    command: mpirun -n 4 vasp_std > vasp.out
    compress_output: true

[subworkflow_kwargs]
command = "mpirun -n 4 vasp_std > vasp.out"
compress_output = true

subworkflow_kwargs=dict(
    command="mpirun -n 4 vasp_std > vasp.out",
    compress_output=True,
)

subworkflow_name

This parameter is the name of workflow that used to evaluate structures generated. Any workflow that is registered and accessible via the get_workflow utility can be used instead. If you wish to submit extra arguments to each workflow run, you can use the subworkflow_kwargs parameter.

subworkflow_name: relaxation.vasp.staged

subworkflow_name = "relaxation.vasp.staged"

subworkflow_name = "relaxation.vasp.staged"

supercell_end

This parameter is the endpoint image supercell to use. This is really just a structure parameter under a different name, so everything about the structure parameter also applies here.

supercell_start

This parameter is the starting image supercell to use. This is really just a structure parameter under a different name, so everything about the structure parameter also applies here.

symmetry_precision

If standardize_structure=True, then this is the cutoff value used to determine if the sites are symmetrically equivalent. (in Angstroms)

symmetry_precision: 0.1

symmetry_precision = 0.1

tags

When submitting workflows via the run_cloud command, tags are 'labels' that help control which workers are allowed to pick up and run the submitted workflow. Workers should be started with matching tags in order for these scheduled flows to run.

When no tags are set, the following default tags will be used for a Simmate workflow:

  • simmate (this is the default worker tag as well)
  • the workflow's type name
  • the workflow's app name
  • the full workflow name

For example, the static-energy.vasp.matproj would have the following tags: 

- simmate
- static-energy
- vasp
- static-energy.vasp.matproj

To override these default tags, use the following:

tags:
    - my-tag-01
    - my-tag-02

tags = ["my-tag-01", "my-tag-02"]

tags = ["my-tag-01", "my-tag-02"]

Warning

When you have a workflow that is submitting many smaller workflows (such as structure-prediction workflows), make sure you set the tags in the subworkflow_kwargs settings: 

subworkflow_kwargs:
    tags:
        - my-tag-01
        - my-tag-02

Bug

Filtering tags does not always work as expected in SQLite3 because a worker with my-tag will incorrectly grab jobs like my-tag-01 and my-tag-02. This issue is known by both Django and SQLite3. Simmate addresses this issue by requiring all tags to be 7 characters long AND fully lowercase when using SQLite3.

temperature_end

For molecular dynamics simulations, this is the temperature to end the simulation at (in Kelvin). This temperature will be reached through a linear transition from the temperature_start parameter.

temperature_end: 1000

temperature_end = 1000

temperature_start

For molecular dynamics simulations, this is the temperature to begin the simulation at (in Kelvin).

temperature_start: 250

temperature_start = 250

temperature_start = 250

threads

For BadELF algorithms, determines how many threads will be used during pybader calculations. If None this will be automatically set to 90% of available threads.

threads: 8

threads = 8

threads = 8

time_step

For molecular dynamics simulations, this is time time between each ionic step (in femtoseconds).

time_step: 1.5

time_step = 1.5

time_step = 1.5

updated_settings

(experimental feature) Unique to customized.vasp.user-config. This is a list of parameters to update the workflow_base with. This often involves updating the base class attributes.

vacancy_mode

For NEB and diffusion workfows, this determines whether vacancy or interstitial diffusion is analyzed. Default of True corresponds to vacancy-based diffusion.

vacancy_mode: false

vacancy_mode = false

vacancy_mode = False

validator_kwargs

(advanced users only) This parameter is a dictionary of extra conditions to use when initializing the validator class. MyValidator(**validator_kwargs). This is closely tied with the validator_name parameter.

validator_name

(experimental feature; advanced users only) This parameter is the base validator class that should be used. The class will be initialized using MyValidator(**validator_kwargs). The input should be given as a string.

Warning

Currently, we only support CrystallNNFingerprint validation, so this should be left at its default value.

workflow_base

(experimental feature) Unique to customized.vasp.user-config. This is the base workflow to use when updating critical settings.

write_electride_files

This parameter is unique to BadELF workflows. If set to True and ELFCAR and CHGCAR will be written containing only the values where the volume belongs to an electride and zero elsewhere.

write_electride_files: false

write_electride_files = false

write_electride_files = False

write_ion_radii

This parameter is unique to BadELF workflows. If set to True, the ionic radii of each atom determined from the ELF will be written to a summary file.

write_ion_radii: true

write_ion_radii = true

write_ion_radii = True

write_labeled_structure

This parameter is unique to BadELF workflows. If set to True, the structure labeled with non-atomic ELF features (e.g. bare electrons, covalent bonds, metal bonds) will be written to a summary file.

write_labeled_structure: true

write_labeled_structure = true

write_labeled_structure = True

write_summary_files

This parameter determines whether or not to write output files. For some workflows, writing output files can cause excessive load on the database and possibly make the calculation IO bound. In cases such as this, you can set this to False.

write_summary_files: false

write_summary_files = false

write_summary_files = False

Tip

Beginners can often ignore this setting. This is typically only relevant in a setup where you have many computational resources and have many evolutionary searches (>10) running at the same time.