Target Property Module

Abstract Base Class

class orchestrator.target_property.property_base.TargetProperty(**target_property_args)

Bases: Recorder, ABC

General class to manage target property calculations

Parameters:

target_property_args – general argument structure which is specified by individual implementations

__init__(**target_property_args)

Parameters:

target_property_args (dict) – general argument structure which is specified by individual implementations

abstract checkpoint_property()

checkpoint the property module into the checkpoint file

save necessary internal variables into a dict with key checkpoint_name and write to the (json) checkpoint file for restart capabilities

abstract restart_property()

restart the property module from the checkpoint file

check if the checkpoint_file has an entry matching the checkpoint_name and set internal variables accordingly if so

abstract calculate_property(iter_num=0, modified_params=None, potential=None, workflow=None, storage=None, **kwargs)

Perform analysis to calculate a property of interest.

Derived classes should list explicit arguments required to calculate their properties. This module can utilize other modules within the orchestrator to carry out the target calculations.

Parameters:

• potential (str) – interatomic potential to be used in LAMMPS

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

  Default: None

Returns:

a dictionary with property output, errors, and calc ids as a tuple (different indices can correspond to different calc types)

Return type:

dict

abstract conduct_sim(sim_params, workflow, sim_path)

Perform the simulation for the target property calculations

sim_params is a dictionary of key-value pairs that can be used to define various parameters related to conducting simulations (e.g. temperature, pressure, random seed, etc..). The dictionary is described in the input json file.

Parameters:

• sim_params (dict) – simulation specific parameters

• workflow (Workflow) – the workflow for managing job submission

• sim_path (str) – path to perform simulations for target property calculations

Return type:

int

abstract calculate_with_error(n_calc, modified_params=None, potential=None, workflow=None)

Calculate a target property with mean and standard deviation Derived classes should list explicit arguments required to calculate their properties.

Mean and standard deviation will be obtained from multiple number of calculations (n_calc)

Parameters:

• n_calc (int) – total number of calculations to perform

• potential (str) – interatomic potential to be used in LAMMPS

• workflow (Workflow) – the workflow for managing job submission

Returns:

mean and standard deviation of the calculated property

Concrete Implementations

Melting Point

class orchestrator.target_property.melting_point.MeltingPoint(**target_property_args)

Bases: TargetProperty

Class for determining melting point of a material

Explore temperature range and determine final temperature that results in solid/liquid phase. Simulation parameters and required paths are read from json file.

Parameters:

• target_property_args – dict with the input parameters. The parameters include:

• path_type (str) – path to perform target property calculations

• model_path (str) – path to store the potential file

• init_config (str) – path to pull configuration files

• init_config_use (boolean) – option to use an initial config file

• gpu_use (boolean) – option to use gpu for running simulations

• random_seed_use (boolean) – option to use random seed in the simulation

• melting_calc_params (dict) – melting point estimation specific parameters

• sim_params (dict) – simulation specific parameters

• simulator_type (str) – name of the simulator to perform simulations

• simulator_path (str) – path to the simulator executable

• elements (list) – list of elements which are present in the simulation

• input_template (dict) – LAMMPS template input files. This is a dictionary of key-value pairs that can be used to define any simulation input template files required for conducting simulations (e.g. one input simulations).

__init__(**target_property_args)

Initialization of the MeltingPoint class with args dict

Parameters:

• target_property_args – dict with the input parameters. The parameters include:

• path_type (str) – path to perform target property calculations

• model_path (str) – path to store the potential file

• init_config (str) – path to pull configuration files

• init_config_use (boolean) – option to use an initial config file

• gpu_use (boolean) – option to use gpu for running simulations

• random_seed_use (boolean) – option to use random seed in the simulation

• melting_calc_params (dict) – melting point estimation specific parameters

• sim_params (dict) – simulation specific parameters

• job_details (dict) – optional parameters for running the job

• simulator_type (str) – name of the simulator to perform simulations

• simulator_path (str) – path to the simulator executable

• elements (list) – list of elements which are present in the simulation

• input_template (dict) – LAMMPS template input file. This is a dictionary of key-value pairs that can be used to define any simulation input template files required for conducting simulations (e.g. one input template for npt simulations and another inpute template for nph simulations).

checkpoint_property()

checkpoint the property module into the checkpoint file

save necessary internal variables into a dict with key checkpoint_name and write to the (json) checkpoint file for restart capabilities

Return type:

None

restart_property()

restart the property module from the checkpoint file

check if the checkpoint_file has an entry matching the checkpoint_name and set internal variables accordingly if so

Return type:

None

calculate_property(iter_num=0, modified_params=None, potential=None, workflow=None, storage=None, **kwargs)

Find final equilibrium temperature for the melting point

Iterate over range of temperatures between temp_min and temp_max, and adjust the temperature range depending on the analysis of liquid and solid phases. Continue spawning simulations with different temperatures until difference between maximum and minimum temperatures reduces below a set threshold (temp_threshold). After finding equilibrium temperature, perform NPH simulations and check if two phases exist by analyzing q_x parameter. Adjust the temperature until getting two phases.The extract_q and extract_msd methods from AnalyzeLammpsLog calculate local bond parameter q_x and mean square displacement, respectively. Additional parameters used by this method are temp_threshold (float, threshold temperature difference between temp_max and temp_min to determine the convergence of the final equilibriumm temperature), temp_min (float, min temperature guess), temp_max (float, max temperature guess), temp_incr (float, temperature increment for screening temperature in NPH stage),num_temp (int, number of temperatures to test between minimum and maximum temperature guesses, max_iter (int, maximum number of iterations for screening temperature in NPH stage). These are defined by self.melting_calc_params and set at class instantiation. This method also uses temp (float, simulation temperature), press (float, simulation pressure), which are defined by self.sim_params and set at class instantiation.

Parameters:

• iter_num (int) – iteration number of the calculation of melting point if executed over multiple iterations

• modified_params (dict) – simulation parameters to modify the initially provided values, including interatomic potentials, simulation temperature and pressure

• workflow (Workflow) – the workflow for managing job submission

• potential (str or Potential) – interatomic potential to be used in LAMMPS. Can be either the string of a KIM potential available via the KIM API or a Potential object created by the Orchestrator.

Returns:

dictionary with the final temperature that results in solid/ liquid phases as the property_value, std based on time-averaging for the property_std, and a tuple of the NPT calculation ID list and the final NPH calculation ID as the calc_ids

Return type:

dict

conduct_sim(sim_params, workflow, sim_path)

Perform simulations for the target property calculations

Additional parameters used by this method are temp (float, simulation temperature), press (float, simulation pressure), ice_temp (float, ice temperature), below_temp_diff (float, temperature to subtract to define below temperature), above_temp_diff (float, temperature to add to define above temperature), farabove_temp_diff (float, temperature to add to define far above temperature), units (string, units to be used in LAMMPS simulations), atom_style (string, atom style name), pair_style (string, pair style name), potential (string, potential name), element (string, type of element), mass (float, mass of the element), lattice (string, lattice type), lattice_param (float, lattice spacing), lx, ly, lz (int, lattice numbers in x, y and z directions), timestep (float, timestep size in time units), q_num_neigh (int, number of nearest neighbors for q_x calculations), nph_steps (int, number of steps for the NPH stage) which are defined by self.sim_params and set at class instantiation. These parameters are modified by calculate_property method on-the-fly and supplied to this method for setting simulation temperature and pressure.

Parameters:

• workflow (Workflow) – the workflow for managing job submission

• sim_path (str) – path to perform simulations for target property calculations

Returns:

path corresponding to a spawned simulation

Return type:

string

calculate_with_error(n_calc, modified_params=None, potential=None, workflow=None)

Calculate a target property with mean and standard deviation

Mean and standard deviation will be obtained from multiple number of calculations (n_calc)

Parameters:

• n_calc (int) – total number of calculations to perform

• modified_params (dict) – simulation parameters to modify the initially provided values, including interatomic potentials, simulation temperature and pressure

• potential (str) – interatomic potential to be used in LAMMPS

• workflow (Workflow) – the workflow for managing job submission

Returns:

dictionary with the average final temperature that results in solid/liquid phases as the property_value, std from the n_calc outputs for the property_std, and a tuple with no NPT and all the final NPH calculation IDs as the calc_ids

Return type:

dict

save_configurations(calc_ids, storage, dataset_handle, workflow)

save configurations generated by the melting point module

Parameters:

• path_ids (list of int or int) – single or list of calc_ids associated with simulator jobs. The path is extracted from the JobStatus.

• storage (Storage) – storage module that hosts the dataset

• dataset_handle (str) – handle for the dataset where configs will be stored

• workflow (Workflow) – the workflow that managed job submission for the provided calc_id

Returns:

updated dataset_handle including the new configurations

Return type:

str

check_density(phase, density_npt, exp_den_solid, exp_den_liquid, den_tol, calc_id)

check if density is within an expected range during npt simulations

Parameters:

• phase (str) – phase detected in the simulation (e.g. solid, liquid)

• density_npt (float) – density calculated from the npt simulations

• exp_den_solid (float) – expected density of the material from the experiments. This does not need to be exact value, especially if the experimental value is not available

• exp_den_liquid (float) – expected density of the material from the experiments. This does not need to be exact value, especially if the experimental value is not available

• den_tol (float) – density tolerance to allow calculated density to deviate from the experimental value

• calc_id (int) – calculation id associated with a simulator job

Return type:

None

static sample_configs(beg, end, step, elements_list, traj_name='dump.lammpstrj', calc_ids=None, workflow=None, in_paths=None)

sample configurations from the NPT or NPH simulations

Parameters:

• beg (int) – first frame of the trajectory to start sampling

• end (int) – final frame of the trajectory for sampling

• step (int) – frequency of sampling configurations from beg to end

• elements_list (list of str) – list of elements in same order that they were passed to the simulator. Used to correctly assign chemical IDs to extracted ASE Atoms

• traj_name (str) – name of the trajectory used for sampling

  Default: ‘dump.lammpstrj’

• calc_ids (list of int) – list of calc_ids associated with simulator jobs. The path is extracted from the JobStatus.

  Default: None

• workflow (Workflow) – the workflow that managed job submission for the provided calc_id. Required if calc_ids are given.

  Default: None

• in_paths (list of str) – list of paths that include trajectories to use for sampling. This option can be used in case calc_ids are not available. If used, workflow does not need to be provided.

  Default: None

Returns:

a list of ASE Atoms objects

Return type:

list

Elastic Constants

class orchestrator.target_property.elastic_constants.ElasticConstants(**target_property_args)

Bases: TargetProperty

Class for determining elastic constants of a material

Calculate elastic constants using a variety of atomic displacements.

Parameters:

target_property_args (dict) – dict with the input parameters. The parameters include: lattice_param (float) - lattice parameter in A lattice_type (str) - sc, bcc, fcc, hcp, or diamond [default = sc] deformation_mag (float) - deformation magnitude [default = 1e-4] units (str) - eV/A3 or GPa options [default = eV/A3] simulator_path (str) - path to the lammps executable for use elements (list) - list of element symbols included in the calculation tolerances, iteration maxes?

__init__(**target_property_args)

Class for determining elastic constants of a material

Calculate elastic constants using a variety of atomic displacements.

Parameters:

target_property_args (dict) – dict with the input parameters. The parameters include: lattice_param (float) - lattice parameter in A lattice_type (str) - sc, bcc, fcc, hcp, or diamond [default = sc] deformation_mag (float) - deformation magnitude [default = 1e-4] units (str) - eV/A3 or GPa options [default = eV/A3] simulator_path (str) - path to the lammps executable for use elements (list) - list of element symbols included in the calculation tolerances, iteration maxes?

checkpoint_property()

checkpoint the property module into the checkpoint file

save necessary internal variables into a dict with key checkpoint_name and write to the (json) checkpoint file for restart capabilities

restart_property()

restart the property module from the checkpoint file

check if the checkpoint_file has an entry matching the checkpoint_name and set internal variables accordingly if so

calculate_property(iter_num=0, modified_params=None, potential=None, workflow=None, storage=None, **kwargs)

Find elastic constants

Use a modified version of Aidan Thompson’s elastic constant calculation script to compute the elastic properties of a KIM potential

Parameters:

• iter_num (int) – iteration number of the calculation of elastic constants if executed over multiple iterations

• modified_params (dict) – simulation parameters to modify the initially provided values, including lattice_param, lattice_type, and deformation_mag

• potential (str or Potential) – interatomic potential to be used in LAMMPS. Can be either the string of a KIM potential available via the KIM API or a Potential object created by the Orchestrator. We only support KIM Potentials at this time.

• workflow (Workflow) – the workflow for managing job submission

Returns:

dictionary with the elastic constant tensor as the property_value, None for the property_std, and the calculation id as the calc_ids

Return type:

array of floats

conduct_sim(sim_params, workflow, sim_path)

Perform simulations for the target property calculations

This function finalizes the simulator run conditions. Since the calc requires the generation of multiple files prior to running, we also set the Simulator’s external_setup flag to True and provide a function for generating these files.

Parameters:

• sim_params (dict) – parameters that define the Simulator run, including the details that are set in the input script as well as the path to the model that should be used

• workflow (Workflow) – the workflow for managing job submission

• sim_path (str) – path name to specify these calculations

Returns:

calculation ID

Return type:

int

calculate_with_error(n_calc, modified_params=None, potential=None, workflow=None)

Calculate a target property with mean and standard deviation Derived classes should list explicit arguments required to calculate their properties.

Mean and standard deviation will be obtained from multiple number of calculations (n_calc)

Parameters:

• n_calc (int) – total number of calculations to perform

• potential (str) – interatomic potential to be used in LAMMPS

• workflow (Workflow) – the workflow for managing job submission

Returns:

mean and standard deviation of the calculated property

save_configurations(calc_ids, dataset_handle, workflow, storage)

KIMRun

class orchestrator.target_property.kimrun.KIMRun(container_manager='podman', image_path='ghcr.io/openkim/developer-platform:v1.7.8-minimal', **kwargs)

Bases: TargetProperty

Class for calculating properties using KIM Tests

CODE_TO_DIR = {'MD': 'model-drivers', 'MO': 'models', 'SM': 'simulator-models', 'TD': 'test-drivers', 'TE': 'tests'}

__init__(container_manager='podman', image_path='ghcr.io/openkim/developer-platform:v1.7.8-minimal', **kwargs)

Class for calculating properties using KIM Tests

Parameters:

• container_manager (str) – Whether to use singularity or podman.

• image_path (PathLike) –

  For podman, this should point to a KIM Developer Platform (KDP) image (https://github.com/openkim/developer-platform). For all possible ways to specify this, see https://docs.podman.io/en/latest/markdown/podman-run.1.html#image By default, this points to a pinned version of the minimal KDP in the GitHub Container Registry (grcr.io), which will automatically be downloaded at runtime if needed. For Singularity, this should be a path to a local Singularity image file, built like this from the Docker image:

  singularity build foo.sif \
  docker://ghcr.io/openkim/developer-platform:v1.7.8-minimal
  

checkpoint_property()

checkpoint the property module into the checkpoint file

save necessary internal variables into a dict with key checkpoint_name and write to the (json) checkpoint file for restart capabilities

restart_property()

restart the property module from the checkpoint file

check if the checkpoint_file has an entry matching the checkpoint_name and set internal variables accordingly if so

calculate_property(get_test_result_args, flatten=False, iter_num=0, potential=None, workflow=None, storage=None, **kwargs)

Run potential against a list of KIM tests

Parameters:

• get_test_result_args (Union[list[dict],dict]) – Inputs to a get_test_result KIM Query as a dictionary of keyword arguments. The model argument should be omitted, as it will be taken from the potential input. See https://openkim.org/doc/usage/kim-query/#get_test_result for info. This determines the output of this module. If a list of dictionaries is passed, multiple query results will be returned.

• flatten (bool) – whether to flatten the (doubly+) nested list returned

• iter_num (int) – iteration number

• potential (str or Potential) – interatomic potential to use, specified as a Potential object (must be able to write a KIM API-compliant model using Potential._save_potential_to_kimkit()) or a string naming a potential already installed in KIMKit.

• workflow (Workflow) – the workflow for managing job submission

Returns:

dictionary with None for the property_std, calculation id as the calc_ids, and a list of query results for the property_value. By default, property_value will be a doubly or more nested list. First index is over each dictionary in ‘get_test_result_args’. Second index is over the number of times the queried Test returned the queried property (e.g. multiple surface energies) Third index is over the keys requested within the property. The values may be arrays of arbitrary dimension themselves. If ‘flatten’ is set to true, this is all flattened into a 1-D numpy array of floats.

Return type:

dict

conduct_sim(sim_params, workflow, sim_path)

Perform simulations for the target property calculations

Parameters:

• sim_params (dict) – parameters that define the containerized run, including test_list, image_path and potential_name

• workflow (Workflow) – the workflow for managing job submission

• sim_path (PathLike) – path name to specify these calculations

Returns:

calculation ID

Return type:

int

calculate_with_error(n_calc, modified_params=None, potential=None, workflow=None)

Calculate a target property with mean and standard deviation Derived classes should list explicit arguments required to calculate their properties.

Mean and standard deviation will be obtained from multiple number of calculations (n_calc)

Parameters:

• n_calc (int) – total number of calculations to perform

• potential (str) – interatomic potential to be used in LAMMPS

• workflow (Workflow) – the workflow for managing job submission

Returns:

mean and standard deviation of the calculated property

save_configurations(calc_ids, dataset_handle, workflow, storage)

Analysis sub-module

Analyze Lammps Log

class orchestrator.target_property.analysis.analyze_log.AnalyzeLammpsLog(ifile)

Bases: object

Class for handling lammps log files.

This class is adapted from henriasv.github.io/lammps-logfile

Parameters:

ifile (string) – path to lammps log file

__init__(ifile)

read_file_to_dict(log_file)

Store lammps log data into a dictionary

Parameters:

ifile (string) – path to lammps log file

flush_dict_and_set_new_keyword(keywords)

get(entry_name, run_num=-1)

Get time-series from log file by name.

If the rows in the log file changes between runs, the logs are being flushed.

Parameters:

• entry_name (str) – Name of the entry, for example ‘Temp’

• run_num (int) – Lammps simulations commonly involve several run-commands. Here you may choose what run you want the log data from. Default of -1 returns data from all runs concatenated

get_keywords(run_num=-1)

Return list of available data columns in the log file.

to_exdir_group(name, exdirfile)

get_num_partial_logs()

static extract_msd(args)

Reads lammps log file and extract required data

This function can be used to determine if the system is solid or liquid using mean square displacement analysis

static extract_density(args)

This function can be used to determine if the system is solid or liquid using mean square displacement analysis

static extract_q(args)

Reads lammps output file and extract required data

This function can be used to determine if the system is solid or liquid using q parameter

Extract Elastic Compliance

orchestrator.target_property.analysis.elastic_constants_analysis.elastic_compliance(data_path)

read lammps output to extract elastic constants (and compliance matrices)

Parameters:

data_path (str) – path, including filename to the LAMMPS output file to read