smc_lammps package

smc_lammps.main()

The entry point for the smc-lammps cli.

Use smc-lammps -h for help.

See smc_lammps.run.get_parser() for the parser definition.

Subpackages

Submodules

smc_lammps.console module

smc_lammps.console.warn(message)

Prints the warning message in a panel.

smc_lammps.run module

exception smc_lammps.run.MaxIterationExceeded

Bases: RuntimeError

Raised when a loop exceeds a large number of iterations.

MAX_ITER: int = 10000

Number of iterations after which a MaxIterationExceeded should be raised.

class smc_lammps.run.TaskDone(skipped: bool = False)

Bases: object

A task.

Tasks may be skipped, e.g. if the corresponding flag is not set.

__init__(skipped: bool = False) → None
smc_lammps.run.clean(args: Namespace, path: Path) → TaskDone

Cleans a simulation directory.

Removes all files in a simulation directory, keeping only paremeters.py.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

Returns:

Task completion information.

smc_lammps.run.create_perspective_file(args: Namespace, path: Path, subdir: Path | None) → Path

Creates a new LAMMPS trajectory file, following a certain perspective.

Runs the smc_lammps.post_process.smc_perspective() script.

Currently supports arms and kleisin perspective following the SMC.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • subdir – Directory or file passed via the cli, relative to path.

Returns:

Task completion information.

smc_lammps.run.execute(args: Namespace)

Executes a sequence of tasks depending on the provided arguments.

The following tasks are executed (if enabled) in order:
Parameters:

args – Parsed arguments.

smc_lammps.run.find_simulation_base_directory(path: Path) → tuple[Path, Path | None]

Finds the base of a simulation directory.

Finds the base of a simulation directory by traversing up the file tree. The base directory is the (first) directory containing a valid parameters.py file.

Attention

The validity of the parameters.py file is not checked by this function!

Parameters:

path – Path to start from, may be a file.

Returns:

Tuple of (base simulation directory, subdirectory to path relative to the base directory if any).

Raises:

  • FileNotFoundError – Root directory was reached without any parameters.py files along the way.

  • MaxIterationExceeded – Exceeded maximum amount of file tree traversal.

smc_lammps.run.generate(args: Namespace, path: Path) → TaskDone

Runs the generation script.

Runs the smc_lammps.generate.generate() script, passing the args.seed as an argument if set.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

Returns:

Task completion information.

smc_lammps.run.get_lammps_args_list(lammps_vars: Sequence[list[str]]) → list[str]

Converts argument list of variables to the LAMMPS format.

Example:
>>> from smc_lammps.run import get_lammps_args_list
>>> get_lammps_args_list([['is_restart', '1'], ['seed', '1234']])
['-var', 'is_restart', '1', '-var', 'seed', '1234']
Parameters:

lammps_vars – Variable names and values.

Returns:

LAMMPS variable definitions which can be passed via the cli.

smc_lammps.run.get_parser() → ArgumentParser

Returns the parser for the smc-lammps cli.

Returns:

parser

smc_lammps.run.get_version() → str | None

Returns the version of the smc-lammps package.

Returns:

Version string in the “x.y.z” format, or None if the version could not be obtained.

smc_lammps.run.initialize(args: Namespace, path: Path) → TaskDone

Initializes a simulation directory.

Creates the directory if it does not exist yet, and places a template parameters.py file inside.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

Returns:

Task completion information.

Raises:

FileExistsError – The path is non-empty and the –force flag is not set.

smc_lammps.run.keep_every(args: Namespace, path: Path, subdir: Path | None) → TaskDone

Edits LAMMPS trajecory file in-place, keeping every nth timestep.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • subdir – File passed via the cli, relative to path.

Returns:

Task completion information.

smc_lammps.run.main()

The entry point for the smc-lammps cli.

Use smc-lammps -h for help.

See smc_lammps.run.get_parser() for the parser definition.

smc_lammps.run.merge(args: Namespace, path: Path) → TaskDone

Merges lammpstrj files together.

Merges lammpstrj files together by calling merge_lammpstrj() on any files that match the output.lammpstrj* glob pattern.

This can be useful after a restart run.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

Returns:

Task completion information.

smc_lammps.run.parse(argv: list[str]) → Namespace

Parses the argument list and returns argparse Namespace.

Parses the arguments before ‘–’, and sets the sub_args field of the returned object to the remaining arguments after ‘–‘.

Parameters:

argv – Unprocessed argument list (from sys import argv).

Returns:

Object holding command line options.

smc_lammps.run.parse_with_double_dash(parser: ArgumentParser, args: list[str]) → tuple[Namespace, list[str]]

Parse arguments with ‘–’ splitting.

Parses arguments by splitting before and after ‘–‘. Arguments before ‘–’ are parsed by the provided parser, everything after is collected into a separate, non-parsed list

Parameters:

  • parser – Parser for arguments before ‘–‘.

  • args – Argument list.

Returns:

Tuple of (parsed arguments before ‘–’, unparsed arguments after ‘–‘).

smc_lammps.run.perform_run(args: Namespace, path: Path, log_file_name: str = 'log.lammps', **kwargs: str | list[str])

Performs a LAMMPS run.

Executes the LAMMPS cli in a new process.

Relevant arguments are passed to LAMMPS, such as -sf and -log.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • log_file_name – File name (relative to output_path) passed to the LAMMPS cli -log argument.

  • kwargs – These parameters are passed to the LAMMPS cli as variables. lammps_root_dir, output_path, output_file_name.

Raises:

ValueError – The output_path contains spaces which will (likely) break the LAMMPS script(s).

smc_lammps.run.post_process(args: Namespace, path: Path) → TaskDone

Performs post-processing.

Runs the smc_lammps.post_process.process_displacement() script.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

Returns:

Task completion information.

smc_lammps.run.quiet_print(quiet: bool, *args, **kwargs)

Calls print if quiet is False.

Parameters:

quiet – if True, do not print.

smc_lammps.run.restart_run(args: Namespace, path: Path, output_file: Path) → TaskDone

Performs a LAMMPS restart run.

Calls smc_lammps.run.perform_run() with the is_restart variable set to ‘1’.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • output_file – The output file (e.g. output.lammpstrj) of the run that will be restarted.

Returns:

Task completion information.

Raises:

  • FileNotFoundError – The output_file does not exist.

  • FileExistsError – Could not find any available file names for the new output.

smc_lammps.run.run(args: Namespace, path: Path) → TaskDone

Runs (or restarts) a simulation.

Dispatches to smc_lammps.run.restart_run() first. If the restart run was skipped, starts a new run via smc_lammps.run.perform_run().

Any existing output_file will only be overwritten if the –force flag is set, otherwise the function will return early.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

Returns:

Task completion information.

smc_lammps.run.run_and_handle_error(process: Callable[[], CompletedProcess], ignore_errors: bool, quiet: bool)

Runs a process and checks the exit code.

Runs a process and handles any non-zero exit code. If the exit code is non-zero and ignore_errors is false, the script exits.

Parameters:

  • process – A function that runs a process when called.

  • ignore_errors – If True, do not exit when the process exit code is non-zero.

  • quiet – Passed to quiet_print.

smc_lammps.run.start_visualize_script(args: Namespace, path: Path, other_args: list[str])

Runs the smc_lammps.post_process.visualize() script.

Runs the smc_lammps.post_process.visualize() script in a new process.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • other_args – Arguments passed to the smc_lammps.post_process.visualize() script.

smc_lammps.run.visualize(args: Namespace, path: Path, subdir: Path | None) → TaskDone

Starts VMD with a certain visualization.

Dispatches to the following tasks in order:
Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • subdir – Directory or file passed via the cli, relative to path.

Returns:

Task completion information.

Raises:

ValueError – The path given by path/subdir is not a file.

smc_lammps.run.visualize_datafile(args: Namespace, path: Path, subdir: Path | None) → TaskDone

Starts VMD with the initial datafile loaded.

Loads the datafile_positions (produced by the smc_lammps.run.generate() step) into VMD.

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • subdir – Directory or file passed via the cli, relative to path.

Returns:

Task completion information.

smc_lammps.run.visualize_follow(args: Namespace, path: Path, subdir: Path | None) → TaskDone

Creates a perspective file and opens it in VMD.

Runs smc_lammps.run.create_perspective_file() to generate a new perspective file, followed by smc_lammps.run.start_visualize_script().

Parameters:

  • args – Parsed arguments.

  • path – Simulation base path.

  • subdir – Directory or file passed via the cli, relative to path.

Returns:

Task completion information.