mdse.cli

Command-Line Interface (CLI) for the MDSE package.

This module defines the main entry point and command structure for interacting with the MDSE (Molecular Dynamics Simulation Engine) package from the command line. It uses Python’s argparse library to create a powerful and user-friendly interface with multiple subcommands.

The CLI supports a wide range of functionalities, including:

• Simulation Management:

  • simulate: Run molecular dynamics simulations from a YAML configuration file, with support for MPI for parallel execution.

• Data Analysis:

  • msd: Calculate and visualize the Mean Square Displacement.

  • lindemann: Calculate the Lindemann index.

  • self_diff: Calculate the self-diffusion coefficient.

  • ish: Calculate the isobaric specific heat.

• Database Interaction:

  • write_db: Write simulation results from JSON files to a MongoDB database.

  • visualize: Generate plots from data stored in the database.

  • outliers: Detect and report outlier data points in the database.

• Visualization and File Management:

  • view: Open and inspect crystal structure files (.traj) using ASE’s GUI.

  • clean: Remove simulation trajectory files (.traj) from a directory.

• Documentation:

  • build_docs: Build the project’s Sphinx documentation locally.

  • view_docs: Open the locally built documentation in a web browser.

The main() function serves as the primary entry point, which parses command-line arguments, sets up logging, and dispatches the request to the appropriate handler function.

Functions

build_website_locally(args)	Build the Sphinx documentation locally.
calc_isobaric_specific_heat(args)	Call the isobaric specific heat calculation function.
calc_lindemann(args)	Calculate and print the Lindemann index.
calc_msd(args)	Calculate and visualize the mean square displacement (MSD).
calc_self_diff(args)	Calculate and print the self-diffusion coefficient.
calculate_defect_formation_energy(args)	From an existing database calculate the defect formation energies
convert_scalar(v)	Attempt to convert a string to an integer or float.
create_parser()	Create and configure the argument parser for the MDSE CLI.
insert_nested(d, key_path, value)	Insert a value into a nested dictionary using a dot-separated key path.
main()	Main entry point for the MDSE command-line interface.
outlier_detection(args)	Connect to the database and run outlier detection.
parse_config(items)	Parse a list of 'key=value' strings into a nested dictionary.
parse_value(v)	Parse a string value into a scalar or a list of scalars.
remove_all_traj(args)	Remove all .traj files from a specified directory.
simulate(args)	Run molecular dynamics simulations defined in a YAML configuration.
simulate_mpi(args)	MPI-safe simulation: minimal logging, suitable for running under mpirun.
view_crystal(args)	Open one or more crystal structure files in the ASE GUI.
view_website_browser(args)	Open the locally built documentation in default web-browser.
visualize_DB(args)	Generate plots from data in the database using a configuration file.
write_to_database(args)	Write simulation results from JSON files to a MongoDB database.

mdse.cli.build_website_locally(args)

Build the Sphinx documentation locally.

This function runs the Sphinx build command to generate HTML documentation from the source files located in docs/source. The built site will be placed in docs/_build/html.

Parameters:

args (argparse.Namespace) – Command-line arguments. This parameter is unused.

mdse.cli.calc_isobaric_specific_heat(args)

Call the isobaric specific heat calculation function.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (list[str]): Paths to .traj files containing simulation results.

mdse.cli.calc_lindemann(args)

Calculate and print the Lindemann index.

This function processes one or more trajectory files and prints the calculated Lindemann index for each.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (list[str]): Paths to .traj files containing simulation results.

mdse.cli.calc_msd(args)

Calculate and visualize the mean square displacement (MSD).

This function processes one or more trajectory files, calculates the MSD for each, and generates a plot.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (list[str]): Paths to .traj files containing simulation results.

mdse.cli.calc_self_diff(args)

Calculate and print the self-diffusion coefficient.

This function processes one or more trajectory files and prints the calculated self-diffusion coefficient for each.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (list[str]): Paths to .traj files containing simulation results.

mdse.cli.calculate_defect_formation_energy(args)

From an existing database calculate the defect formation energies

Parameters:

args (argparse.address) –

Command-line arguments. Should contain:

• filepath (str): Path to database

mdse.cli.convert_scalar(v)

Attempt to convert a string to an integer or float.

Parameters:

v (str) – The input string to convert.

Returns:

The converted value as an integer or float if successful, otherwise the original string.

Return type:

int | float | str

mdse.cli.create_parser()

Create and configure the argument parser for the MDSE CLI.

This function defines all the commands, subcommands, and their respective arguments, help messages, and default functions to be executed.

Returns:

The fully configured parser object.

Return type:

argparse.ArgumentParser

mdse.cli.insert_nested(d, key_path, value)

Insert a value into a nested dictionary using a dot-separated key path.

Creates nested dictionaries as needed.

Parameters:

• d (dict) – The dictionary to modify.

• key_path (str) – A dot-separated string representing the nested keys (e.g., “a.b.c”).

• value (any) – The value to insert at the specified path.

Notes

This function modifies the input dictionary d in place.

mdse.cli.main()

Main entry point for the MDSE command-line interface.

This function orchestrates the CLI by:

1. Creating the argument parser.

2. Parsing the command-line arguments provided by the user.

3. Setting up the logging configuration (e.g., setting the level to DEBUG if –debug is specified).

4. Dispatching the command to the appropriate handler function based on the subcommand provided.

5. If no subcommand is given, it prints the help message.

Examples

Running a simulation:

>>> mdse simulate -f config.yml

Viewing a trajectory file:

>>> mdse view -f result.traj

Cleaning up trajectory files:

>>> mdse clean -f ./results --recursive

mdse.cli.outlier_detection(args)

Connect to the database and run outlier detection.

Fetches data from a specified MongoDB collection, groups it by chemical formula, and identifies outliers for given physical properties based on a standard deviation threshold.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• address (str): The connection URI for the MongoDB database.

• properties (list[str] | None): A list of properties to check for outliers (e.g., ‘energy_per_atom’).

• db_client (str): The name of the MongoDB database.

• db_collection (str): The name of the collection within the database.

• std_dev (float): The standard deviation threshold for classifying a data point as an outlier.

mdse.cli.parse_config(items)

Parse a list of ‘key=value’ strings into a nested dictionary.

Keys can be dot-separated to create nested structures. For example, ["sim.steps=1000", "potential.name=EAM"] becomes {'sim': {'steps': 1000}, 'potential': {'name': 'EAM'}}.

Parameters:

items (list[str] | None) – A list of strings, each in “key=value” format.

Returns:

A nested dictionary representing the configuration, or None if the input is None.

Return type:

dict | None

mdse.cli.parse_value(v)

Parse a string value into a scalar or a list of scalars.

If the string contains commas, it is split into a list of values. Each value is then converted to an int or float if possible.

Parameters:

v (str) – The string value to parse.

Returns:

The parsed value, which can be a single scalar or a list of scalars.

Return type:

int | float | str | list[int | float | str]

mdse.cli.remove_all_traj(args)

Remove all .traj files from a specified directory.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (str | None): Directory path where .traj files will be removed. If None, defaults to the current directory.

• recursive (bool): If True, also search subdirectories.

Notes

Side Effects: Deletes files from disk and prints status messages for each file.

mdse.cli.simulate(args)

Run molecular dynamics simulations defined in a YAML configuration.

If the –mpi flag is used, this function will dispatch to simulate_mpi for parallel execution.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (str): Path to a YAML file describing simulation parameters.

• mpi (bool): If True, dispatch to the MPI-safe simulation function.

• config (list[str] | None): Optional ‘key=value’ pairs to overwrite configuration from the YAML file.

Notes

Parses the input YAML using main_read(), creates a RunManager, and executes all simulations.

mdse.cli.simulate_mpi(args)

MPI-safe simulation: minimal logging, suitable for running under mpirun. Run molecular dynamics simulations defined in a YAML configuration.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (str): Path to a YAML file describing simulation parameters.

• config (list[str] | None): Optional ‘key=value’ pairs to overwrite configuration from the YAML file.

Notes

Parses the input YAML using main_read(), creates a RunManager, and executes all simulations. This function is intended to be called from simulate() when the –mpi flag is used.

mdse.cli.view_crystal(args)

Open one or more crystal structure files in the ASE GUI.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (list[str] | None): Paths to files to view. If None, opens all .traj files in the current directory.

Notes

Uses the ase gui command under the hood.

mdse.cli.view_website_browser(args)

Open the locally built documentation in default web-browser.

This function launches default web-browser to display the generated HTML documentation at docs/_build/html/index.html.

Parameters:

args (argparse.Namespace) – Command-line arguments. This parameter is unused.

mdse.cli.visualize_DB(args)

Generate plots from data in the database using a configuration file.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• filepath (str): Path to a YAML configuration file that specifies which data to fetch and how to plot it.

mdse.cli.write_to_database(args)

Write simulation results from JSON files to a MongoDB database.

Parameters:

args (argparse.Namespace) –

Command-line arguments. Should contain:

• address (str): The connection URI for the MongoDB database.

• filepath (list[str]): A list of paths to JSON files or directories containing JSON files to be written to the database.