API Reference¶

This comprehensive API reference documents all the functions available in the aMACEing toolkit. The toolkit provides a Pythonic interface for molecular simulations with various engines and trajectory analysis.

Core Simulation APIs¶

CP2K API¶

amaceing_toolkit.cp2k_api(run_type=None, config=None)¶

API function for CP2K input file creation.

Parameters:

run_type (str, optional) – Type of calculation to run (‘GEO_OPT’, ‘CELL_OPT’, ‘MD’, ‘REFTRAJ’, ‘ENERGY’)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Creates input files in the current directory

Examples:

from amaceing_toolkit import cp2k_api

# Geometry optimization
config = {
    'project_name': 'test_geo',
    'coord_file': 'system.xyz',
    'pbc_list': [10.0, 0, 0, 0, 10.0, 0, 0, 0, 10.0],
    'max_iter': 100,
    'print_forces': 'OFF',
    'xc_functional': 'BLYP',
    'cp2k_newer_than_2023x': 'y'
}

cp2k_api(run_type='GEO_OPT', config=config)

MACE API¶

amaceing_toolkit.mace_api(run_type=None, config=None)¶

API function for MACE input file creation.

Parameters:

run_type (str, optional) – Type of calculation to run (‘GEO_OPT’, ‘CELL_OPT’, ‘MD’, ‘MULTI_MD’, ‘FINETUNE’, ‘FINETUNE_MULTIHEAD’, ‘TRAIN’, ‘RECALC’)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Creates input files in the current directory

Examples:

from amaceing_toolkit import mace_api

# MD simulation example
md_config = {
    'project_name': 'test_md',
    'coord_file': 'system.xyz',
    'pbc_list': [14.0, 0, 0, 0, 14.0, 0, 0, 0, 14.0],
    'foundation_model': 'mace_mp',
    'model_size': 'small',
    'dispersion_via_ase': 'n',
    'temperature': 300,
    'nsteps': 10000,
    'timestep': 0.5,
    'thermostat': 'Langevin',
    'write_interval': 10,
    'log_interval': 100,
    'print_ext_traj': 'y',
}

mace_api(run_type='MD', config=md_config)

MatterSim API¶

amaceing_toolkit.mattersim_api(run_type=None, config=None)¶

API function for MatterSim input file creation.

Parameters:

run_type (str, optional) – Type of calculation to run (‘GEO_OPT’, ‘CELL_OPT’, ‘MD’, ‘MULTI_MD’, ‘FINETUNE’, ‘RECALC’)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Creates input files in the current directory

Examples:

from amaceing_toolkit import mattersim_api

# MD simulation example
md_config = {
    'project_name': 'mattersim_md',
    'coord_file': 'system.xyz',
    'pbc_list': [14.0, 0, 0, 0, 14.0, 0, 0, 0, 14.0],
    'foundation_model': 'large',
    'temperature': 300,
    'nsteps': 10000,
    'timestep': 0.5,
    'thermostat': 'Langevin',
    'timestep': 0.5,
    'write_interval': 10,
    'log_interval': 100,
    'print_ext_traj': 'y',
}

mattersim_api(run_type='MD', config=md_config)

SevenNet API¶

amaceing_toolkit.sevennet_api(run_type=None, config=None)¶

API function for SevenNet input file creation.

Parameters:

run_type (str, optional) – Type of calculation to run (‘GEO_OPT’, ‘CELL_OPT’, ‘MD’, ‘MULTI_MD’, ‘FINETUNE’, ‘TRAIN’, ‘RECALC’)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Creates input files in the current directory

Examples:

from amaceing_toolkit import sevennet_api

# MD simulation example
md_config = {
    'project_name': 'sevennet_md',
    'coord_file': 'system.xyz',
    'pbc_list': [14.0, 0, 0, 0, 14.0, 0, 0, 0, 14.0],
    'foundation_model': '7net-0',
    'modal': 'omat',
    'temperature': 300,
    'nsteps': 10000,
    'timestep': 0.5,
    'write_interval': 10,
    'log_interval': 100,
    'print_ext_traj': 'y'
}

sevennet_api(run_type='MD', config=md_config)

ORB API¶

amaceing_toolkit.orb_api(run_type=None, config=None)¶

API function for ORB input file creation.

Parameters:

run_type (str, optional) – Type of calculation to run (‘GEO_OPT’, ‘CELL_OPT’, ‘MD’, ‘FINETUNE’, ‘RECALC’)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Creates input files in the current directory

Examples:

from amaceing_toolkit import orb_api

# MD simulation example
md_config = {
    'project_name': 'orb_md',
    'coord_file': 'system.xyz',
    'pbc_list': [14.0, 0, 0, 0, 14.0, 0, 0, 0, 14.0],
    'foundation_model': 'orb_v3_conservative_inf',
    'modal': 'omat',
    'temperature': 300,
    'nsteps': 10000,
    'timestep': 0.5,
    'thermostat': 'Langevin',
    'write_interval': 10,
    'log_interval': 100,
    'print_ext_traj': 'y'
}

orb_api(run_type='MD', config=md_config)

Grace API¶

amaceing_toolkit.grace_api(run_type=None, config=None)¶

API function for Grace input file creation.

Parameters:

run_type (str, optional) – Type of calculation to run (‘GEO_OPT’, ‘CELL_OPT’, ‘MD’, ‘MULTI_MD’, ‘FINETUNE’, ‘TRAIN’, ‘RECALC’)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Creates input files in the current directory

Examples:

from amaceing_toolkit import grace_api

# MD simulation example
md_config = {
    'project_name': 'grace_md',
    'coord_file': 'system.xyz',
    'pbc_list': [14.0, 0, 0, 0, 14.0, 0, 0, 0, 14.0],
    'foundation_model': 'GRACE-1L-OMAT',
    'temperature': 300,
    'nsteps': 10000,
    'timestep': 0.5,
    'thermostat': 'Langevin',
    'write_interval': 10,
    'log_interval': 100,
    'print_ext_traj': 'y'
}

grace_api(run_type='MD', config=md_config)

Trajectory Analysis¶

Analyzer API¶

amaceing_toolkit.analyzer_api(file=None, pbc=None, timestep=None, visualize='y', rdf_pairs=None, msd_list=None, smsd_list=None, autocorr_pairs=None)¶

API function for trajectory analysis.

Parameters:

file (str or list of str, optional) – [OPTIONAL] Path(s) to the trajectory file(s). Multiple paths possible (e.g., ‘coord1.xyz, coord2.xyz’).
pbc (str or list of str, optional) – [OPTIONAL] Path(s) to the PBC file(s). Multiple paths possible (e.g., ‘pbc1, pbc2’).
timestep (str or list of str, optional) – [OPTIONAL] Timestep(s) in fs. Multiple values possible (e.g., ‘0.5, 1.0’).
visualize (str, optional) – [OPTIONAL] Visualize the analysis (‘y’ or ‘n’). Default is ‘y’.
rdf_pairs (str or list of str, optional) – [OPTIONAL] RDF pairs to consider. Multiple values possible (e.g., ‘O-H, H-H’).
msd_list (str or list of str, optional) – [OPTIONAL] MSD atoms to consider. Multiple values possible (e.g., ‘O, H’).
smsd_list (str or list of str, optional) – [OPTIONAL] sMSD atoms to consider. Multiple values possible (e.g., ‘O, H’).
autocorr_pairs (str or list of str, optional) – [OPTIONAL] Autocorrelation pairs to consider. Multiple values possible (e.g., ‘O-H, H-H’).

Returns:

None - Performs analysis and saves results in the current directory

Examples:

from amaceing_toolkit import analyzer_api

# Analyze a trajectory with visualization
analyzer_api(file='traj.xyz', pbc='pbc.txt', timestep='0.5', visualize='y', rdf_pairs='O-H', msd_list='O', smsd_list='H', autocorr_pairs='O-H')

Utility Functions¶

amaceing_toolkit.utils_api(operation, config=None)¶

API function for various utility operations.

Parameters:

operation (str) – Type of operation (EVAL_ERROR, PREPARE_EVAL_ERROR, EXTRACT_XYZ, CITATIONS, BENCHMARK)
config (dict, optional) – Dictionary with the configuration parameters

Returns:

None - Performs the specified utility operation

Examples:

from amaceing_toolkit import utils_api

# Evaluate error between ground truth and comparison files
eval_config = {
     'ener_filename_ground_truth': 'ref_energies.txt',
     'force_filename_ground_truth': 'ref_forces.txt',
     'ener_filename_compare': 'test_energies.txt',
     'force_filename_compare': 'test_forces.txt'
}
utils_api('EVAL_ERROR', config=eval_config)

# Prepare files for error evaluation from a trajectory
prep_config = {
     'traj_file': 'traj.traj',
     'each_nth_frame': 200,
     'start_cp2k': 'y',
     'log_file': 'mace_input.log',
     'xc_funtional': 'BLYP'
}
utils_api('PREPARE_EVAL_ERROR', config=prep_config)

# Extract XYZ coordinates from a trajectory
extract_config = {
     'coord_file': 'traj.xyz',
     'each_nth_frame': 10
}
utils_api('EXTRACT_XYZ', config=extract_config)

# Get citations from a log file
citations_config = {
     'log_file': 'xxx_input.log'
}
utils_api('CITATIONS', config=citations_config)

# Benchmark example
benchmark_config = {
     'mode': 'MD',
     'coord_file': 'system.xyz',
     'pbc_list': [14.0, 0, 0, 0, 14.0, 0, 0, 0, 14.0],
     'force_nsteps': 10000,
     'mace_model': ['mace_mp', 'small'],
     'mattersim_model': 'large',
     'sevennet_model': ['7net-mf-ompa', 'mpa'],
     'orb_model': ['orb_v3_conservative_inf', 'omat'],
     'grace_model': ['GRACE-1L-OMAT']
}
utils_api('BENCHMARK', config=benchmark_config)