Simulator Module

Abstract Base Class

class orchestrator.simulator.simulator_base.Simulator(simulator_args)[source]

Bases: Recorder, ABC

Abstract base class to manage and run simulations (exploration)

The simulator class manages the construction and parsing of molecular dynamics calculations using interatomic potentials. The input will typically consist of an initial atomic configuration and calculation parameters (including the potential to use), while the output will include frames or configurations from the simulation as well as information such as the energy of the system, forces on each atom, and/or the stress on the cell, amongst others.

Parameters:

simulator_args (dict) – dictionary of parameters to instantiate the Simulator, such as code_path (executable to use), elements (list of elements present in the simulation), and input_template (the path to an input template to build from)

__init__(simulator_args)[source]

Abstract base class to manage and run simulations (exploration)

Parameters:

simulator_args (dict) – dictionary of parameters to instantiate the Simulator, such as code_path (executable to use), elements (list of elements present in the simulation), and input_template (the path to an input template to build from)

default_wf

default workflow to use within the Simulator class

get_init_configs_from_path(config_path, file_ext='.xyz', file_format='extxyz')[source]

get the initial configuration for the simulator input from path

This function loads the configurations present in the config_path and all of its sub-directories into a list of ASE Atoms, which is returned. Assumes files are stored in the extended xyz format. This function should only be used if configurations cannot be added to Storage.

Parameters:

  • config_path (str) – path of the root directory where configuration files are stored (extended xyz format)

  • file_ext (str) – the file extension. Default is ‘.xyz’

  • file_ext – the file format. Default is ‘extxyz’

Returns:

dataset as list of Atoms objects

Return type:

list

run(path_type, model_path, input_args, init_config_args, workflow=None, job_details=None)[source]

setup and execute a Simulator calculation

Prepare input file and initial configuration. Execute the code (run simulation), returning the job_id for tracking purposes

Parameters:

  • path_type (str) – specifier for the workflow path, to differentiate calculation types

  • model_path (str) – path where the potential file(s) is stored

  • input_args (dict) – input arguments to fill out the input template file

  • init_config_args (dict) – dictionary containing information to specify how the configuration should be setup for the run. Key:value pairs are ‘make_config’: boolean if run() should create the initial configuration [if false, the other keys are not needed], ‘config_handle’: identifier to retrieve the configuration, ‘storage’: storage module for configuration options to be retrieved from. Alternatively, set to ‘path’ if config_handle is a path where configs should be read from, ‘random_seed’: if selecting the configuration from a set, an int random seed can be specified to enable reproducability

  • workflow (Workflow) – the workflow for managing job submission, if none are supplied, will use the default workflow defined in this class

    Default: None

  • job_details (dict) – dict that includes any additional parameters for running the job (passed to submit_job())

    Default: None

Returns:

calculation ID

Return type:

int

save_configurations(path_ids, storage, dataset_handle=None, workflow=None)[source]

save the configurations associated with path_ids to storage

Parameters:

  • path_ids (list of int or str) – list of calc_ids or explicit paths associated with simulator jobs. If calc_ids are supplied, the path is extracted from the JobStatus. Otherwise it is taken verbatim as the input.

  • storage (Storage) – the storage module where the configurations will be saved.

  • dataset_handle (str) – the handle to identify where in Storage the configurations should be saved. If None, then the class default (date stamped) is used.

    Default: None

  • workflow (Workflow) – the workflow for managing job submission, if none are supplied, will use the default workflow defined in this class. Should be consistent with the workflow supplied for any run calls.

    Default: None

Returns:

handle of the dataset which includes the new configurations

Return type:

str

abstract write_input(run_path, input_args, input_file_name)[source]

generate an input file for running a simulator calculation

generate an input file using the input_template and input_args for the given structural configuration, written as an external file by write_initial_config()

Parameters:

  • run_path (str) – root path where simulations will run

  • input_args (dict) – additional arguments for the template, model specific

  • input_file_name (str) – name for the input file

abstract write_initial_config(run_path, atoms)[source]

generate an input file for the initial structural configuration

Codes such as LAMMPS have an input file specifying the calculation and a separate input file specifying the structural configuration. This method generates the latter file.

Parameters:

  • run_path (str) – path where the configuration file will be written

  • atoms – the ASE Atoms object

abstract get_run_command(args=None)[source]

return the command to run a simulator calculation

this method formats the run command based on the code_path internal variable set at instantiation of the Simulator, which the Workflow will execute in the proper run_path. The args dictionary can be used to pass any necessary extra parameters to the specific implementations.

Parameters:

args (dict) – dictionary for parameters to decorate or enable the run command

Default: None

Returns:

command to run the simulator

Return type:

str

abstract parse_for_storage(run_path)[source]

process calculation output to extract data in a consistent format

Typically, the output of interest from simulators are the calculation cell and atomic coordinates and type. However, additional information could also be extracted as properties in the ASE Atoms object.

Parameters:

run_path (str) – directory where the simulator output file resides

Returns:

list of ASE Atoms of the configurations and any attached properties. Metadata with the configuration source information is attached to the METADATA_KEY in the info dict.

Return type:

Atoms list

abstract load_potential(run_path, model_path)[source]

set up the potential to be used at run_path

Make the trained model accessible for simulations, i.e. through loading a KIM potential or ensuring the potential files are present in the requisite folder

Parameters:

  • run_path (str) – root path where simulations will run and potential should be loaded/linked

  • model_path (str) – path where the model to load is stored

Concrete Implementations

LAMMPS

class orchestrator.simulator.lammps.LAMMPSSimulator(simulator_args)[source]

Bases: Simulator

Class for preparing input, running, and processing LAMMPS calculations

Responsible for creating lammps and configuration input files, providing commands to run LAMMPS, linking KIM potentials to the LAMMPS run, and parsing the output to extract atomic configurations from trajectories

Parameters:

simulator_args (dict) – dictionary of parameters to instantiate the Simulator, such as code_path (executable to use), elements (list of elements present in the simulation), and input_template (the path to an input template to build from)

__init__(simulator_args)[source]

Class for preparing input, running, and processing LAMMPS calculations

Parameters:

simulator_args (dict) – dictionary of parameters to instantiate the Simulator, such as code_path (executable to use), elements (list of elements present in the simulation), and input_template (the path to an input template to build from)

write_input(run_path, input_args, input_file_name)[source]

generate an input file for running a simulator calculation

generate an input file using the input_template and input_args for the given structural configuration, written as an external file by write_initial_config()

Parameters:

  • run_path (str) – root path where simulations will run

  • input_args (dict) – additional arguments for the template, model specific

  • input_file_name (str) – name for the input file

write_initial_config(run_path, atoms)[source]

Write LAMMPS conf file - initial condintion for simulation

In addition to the lammps input file, the inital configuration is specified in the conf.lmp file. Conf.lmp defines the atomic positions cell parameters, and atomic types, and is saved in the run_path Assuming the cell matrix follows Lammps convention: https://docs.lammps.org/Howto_triclinic.html

Parameters:

  • run_path (str) – path where the configuration file will be written

  • atoms (Atoms) – the configuration to write

get_run_command(args=None)[source]

return the command to run a LAMMPS calculation

this method formats the run command based on the code_path internal variable set at instantiation of the Simulator, which the Workflow will execute in the proper run_path. The args dictionary can be used to pass the GPU flag, gpu_use, to format the run command for GPU execution.

Parameters:

args (dict) – dictionary for parameters to decorate or enable the run command. GPU command is selected with gpu_use set to True in args.

Default: None

Returns:

command to run the simulator

Return type:

str

parse_for_storage(run_path)[source]

process LAMMPS output to extract data in the format for Storage

Typically, the output of interest from simulators are the calculation cell and atomic coordinates and type. However, additional information could also be extracted as properties in the ASE Atoms object.

Parameters:

run_path (str) – directory where the lammps output file resides

Returns:

list of ASE Atoms of the configurations and any attached properties. Metadata with the configuration source information is attached to the METADATA_KEY in the info dict.

Return type:

Atoms

load_potential(run_path, model_path)[source]

set up the potential to be used at run_path

Make the trained model accessible for simulations, i.e. through loading a KIM potential or ensuring the potential files are present in the requisite folder. If model path is not provided, then the code will assume that the model has been loaded in the user enviroment of KIM and is accessible from outside the current directory.

Parameters:

  • run_path (str) – root path where simulations will run and potential should be loaded/linked

  • model_path (str) – path where the model to load is stored

Simulator Builder

class orchestrator.simulator.factory.SimulatorBuilder(factory=<orchestrator.utils.module_factory.ModuleFactory object>)[source]

Bases: ModuleBuilder

Constructor for simulators added in the factory

set the factory to be used for the builder. The default is to use the simulator_factory generated at the end of this module. A user defined ModuleFactory can optionally be supplied instead.

Parameters:

factory (ModuleFactory) – a simulator factory

Default: simulator_factory

__init__(factory=<orchestrator.utils.module_factory.ModuleFactory object>)[source]

constructor for the SimulatorBuilder, sets the factory to build from

Parameters:

factory (ModuleFactory) – a simulator factory

Default: simulator_factory

build(simulator_type, simulator_args=None)[source]

Return an instance of the specified simulator

The build method takes the specifier and input arguments to construct a concrete simulator instance.

Parameters:

  • simulator_type (str) – token of a simulator which has been added to the factory

  • simulator_args – dictionary of parameters to instantiate the Simulator, such as code_path, elements, and input_template

Returns:

instantiated concrete Simulator

Return type:

Simulator

orchestrator.simulator.factory.simulator_builder = <orchestrator.simulator.factory.SimulatorBuilder object>

simulator builder object which can be imported for use in other modules