clinamen2.utils package

Submodules

clinamen2.utils.bipop_restart module

Dataclass and functions for BIPOP-CMA-ES.

References:

[1] N. Hansen. Benchmarking a BI-population CMA-ES on the BBOB-2009 function testbed. In Workshop Proceedings of the GECCO Genetic and Evolutionary Computation Conference. ACM, 2009.

[2] I. Loshchilov. CMA-ES with Restarts for Solving CEC 2013 Benchmark Problems. IEEE Congress on Evolutionary Computation, Jun 2013, Cancun, Mexico. hal-00823880.

class clinamen2.utils.bipop_restart.BIPOP(default_pop_size, default_step_size, random_state, large_restart_counter, latest_large_pop_size, eval_counter)

Bases: object

Dataclass representing the current state of a BIPOP run.

Parameters:

• default_pop_size (int) – Default population size calculated by the CMA-ES.

• default_step_size (float) – Default global variance of the Gaussian.

• random_state (dict) – Dictionary representing the state of the random generator (numpy.random.default_rng()).

• large_restart_counter (int) – Number of restarts with large population.

• latest_large_pop_size (int) – Latest used large population size.

• eval_counter (Tuple[int, int]) – Function evaluations for large and small restarts. Saved in a Tuple[large, small].

default_pop_size: int

default_step_size: float

eval_counter: Tuple[int, int]

large_restart_counter: int

latest_large_pop_size: int

random_state: dict

clinamen2.utils.bipop_restart.bipop_init(default_pop_size, default_step_size, random_state)

Initialize a BIPOP object.

The arguments are ‘default’ with respect to the BIPOP algorithm, not necessarily the CMA-ES default values.

Parameters:

• default_pop_size – Default population size to start with.

• default_step_size – Default step size to start with.

• random_state – State of a numpy random number generator.

Return type:

BIPOP

Returns:

Initial state of the BIPOP.

clinamen2.utils.bipop_restart.bipop_next_restart(bipop)

Calculate pop_size, step_size for next restart.

Also returns an updated BIPOP. The first restart is always a large restart.

Parameters:

• BIPOP – Input state of the BIPOP.

• bipop (BIPOP)

Return type:

Tuple[int, float, BIPOP]

Returns:

tuple containing

• Population size for next restart.

• Step size for next restart.

• New state of the BIPOP.

clinamen2.utils.bipop_restart.bipop_update(bipop, new_evals)

Returns a new BIPOP with updated eval_counter.

The lower counter will be updated.

Parameters:

• bipop (BIPOP) – Input state of the BIPOP.

• new_evals (int) – Evaluation count performed since input state.

Return type:

BIPOP

Returns:

New state of the BIPOP.

clinamen2.utils.file_handling module

Read and write CMA-ES results.

class clinamen2.utils.file_handling.CMAFileHandler(label=None, target_dir=PosixPath('/home/rwanzenboeck/code/github_build/clinamen2-public-releases'))

Bases: object

Handle input and output files.

Parameters:

• label (Optional[str]) – Label of the evolution run.

• target_dir (Path) – Full path to target directory. Default is the current working directory.

get_evolution_filename(label=None)

Return a pathlib.Path object representing the evolution file.

Parameters:

label (Optional[str]) – Label of the evolution run.

Return type:

Path

get_generation_filename(generation, label=None)

Return a pathlib.Path object representing the generation file.

Parameters:

• generation (int) – Generation index.

• label (Optional[str]) – Label of the evolution run.

Return type:

Path

load_evolution(label=None, file_format='json')

Function that loads an evolution from file.

Objects loaded:

‘initial_parameters’: AlgorithmParameters

‘initial_state’: AlgorithmState

‘termination_criterion’: Criterion

any additional compatible information

Parameters:

• label (Optional[str]) – String to be added to filename.

• file_format (str) – Indicate the file format used for serialization. The options are ‘json’ and ‘dill’. Default is ‘json’.

Return type:

Tuple[AlgorithmParameters, AlgorithmState, Criterion, dict]

Returns:

tuple containing

• AlorithmParameters object

• AlgorithmState object

• Criterion object

• Dictionary containing additional objects if present.

load_generation(generation, label=None, allow_legacy=True, file_format='json')

Function that loads a generation from file.

Parameters:

• generation (int) – ID of generation to be loaded.

• label (Optional[str]) – String to be added to filename.

• allow_legacy (bool) – If True, older results containing ‘fitness’

• True. (instead of 'loss' can be loaded. Default is)

• file_format (str) – Indicate the file format used for serialization. The options are ‘json’ and ‘dill’. Default is ‘json’.

Return type:

Tuple[AlgorithmState, numpy.typing.ArrayLike, numpy.typing.ArrayLike, NamedTuple, dict]

Returns:

tuple containing

• AlgorithmState object

• Array of population

• Array of loss values

• NamedTuple of termination state

• Dictionary containing additional objects if present.

save_evolution(initial_parameters, initial_state, termination_criterion=None, label=None, additional=None, file_format='json', json_encoder=<class 'clinamen2.utils.file_handling.JSONEncoder'>)

Function that writes the initial evolution to file.

Accepts any data that is serializable using dill. It might be necessary to use a different JSONEncoder. If ‘additional’ contains dataclasses, use dataclasses.asdict() and take care to manually re-cast after loading.

Serialized data contains:

‘initial_parameters’: AlgorithmParameters

‘initial_state’: AlgorithmState

‘termination_criterion’: Criterion (optional)

any additional compatible information (dill-only)

Filenames:

evolution.json

evolution_ + label + .json

Parameters:

• initial_parameters (AlgorithmParameters) – The initial parameters to start the evolution.

• initial_state (AlgorithmState) – The initial state to start the evolution.

• termination_criterion (Optional[Criterion]) – The termination criterion set up for the evolution. Can be a combinated criterion.

• label (Optional[str]) – String to be added to filename.

• additional (Optional[dict]) – Additional information to be saved with the initial evolution properties.

• file_format (str) – Indicate the file format to be used for serialization. The options are ‘json’ and ‘dill’. Default is ‘json’.

• json_encoder (JSONEncoder) – If default encoder file_handling.JSONEncoder does not offer the required functionality, e.g., JAX datatypes.

Return type:

str

Returns:

Name of generated file.

save_generation(current_state, population, loss, termination_state=None, label=None, additional=None, file_format='json', json_encoder=<class 'clinamen2.utils.file_handling.JSONEncoder'>)

Function that writes a generation to file.

Accepts any data that is serializable using dill.

Serialized data contains:

‘current_state’: AlgorithmState

‘population’: numpy.ArrayLike

‘loss’: numpy.ArrayLike

‘termination_state’: NamedTuple

any additional compatible information in a dictionary

Filenames:

‘generation’ + str(number) + ‘.json’ ‘generation’ + label + ‘_’ + str(number) +’.json’

Parameters:

• current_state (AlgorithmState) – The current state of the evolution.

• population (numpy.typing.ArrayLike) – The population of individuals of the generation.

• loss (numpy.typing.ArrayLike) – Loss of each individual within the population.

• termination_state (Optional[NamedTuple]) – State of termination criterion.

• label (Optional[str]) – String to be added to filename.

• additional (Optional[dict]) – Additional information to be saved with the initial evolution properties.

• file_format (str) – Indicate the file format to be used for serialization. The options are ‘json’ and ‘dill’. Default is ‘json’.

• json_encoder (JSONEncoder) – If default encoder file_handling.JSONEncoder does not offer the required functionality, e.g., JAX datatypes.

Return type:

str

Returns:

Name of generated file.

update_evolution(label=None, additional=None)

Function that calls save_evolution(file_format=’json’).

Accepts all data that is serializable using json. Values for keys that are already present in the existing additional information will be replaced.

Filenames:

evolution.json

evolution_ + label + .json

Parameters:

• label (Optional[str]) – Label of the evolution run.

• additional (Optional[dict]) – Additional information to be saved with the evolution properties.

Return type:

str

Returns:

Name of evolution file.

class clinamen2.utils.file_handling.JSONDecoder(*args, **kwargs)

Bases: JSONDecoder

Class that extends the JSONDecoder to handle different data types.

object_hook(obj)

Reencode numpy arrays from dictionary.

class clinamen2.utils.file_handling.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Class that extends JSONEncoder to handle different data types.

default(o)

Return a json-izable version of o or delegate on the base class.

clinamen2.utils.jax_data module

JSONEncoder that handles DeviceArrays.

Removed from file_handling to avoid jnp dependency.

class clinamen2.utils.jax_data.JSONEncoderwithJNP(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Class that extends JSONEncoder to handle different data types.

Separate version that encodes JNP arrays to numpy.

default(o)

Return a json-izable version of o or delegate on the base class.

clinamen2.utils.lennard_jones module

Implementation of the Lennard Jones potential and related functions.

exception clinamen2.utils.lennard_jones.PositionException

Bases: Exception

Exception to be raised for exceeding position threshold.

clinamen2.utils.lennard_jones.create_evaluate_lj_potential(n_atoms=38, identifier=None, wales_path=None, n_eval_batch=100)

Create an LJ evaluation function from a Cambridge database entry

Load the coordinates of the ground state of an n- atom LJ cluster from an entry in

http://doye.chem.ox.ac.uk/jon/structures/LJ.html

and return the corresponding LennardJones object and an eval function.

Parameters:

• n_atoms (int) – Number of atoms in the cluster.

• identifier (Optional[str]) – Additional identifier of a specific configuration. For example “i” for “38i”. Default is None.

• wales_path (Optional[Path]) – Path to the Wales potential data.

• n_eval_batch – Batchsize to be vmapped.

Return type:

Callable

Returns:

tuple

• Coordinates of specified Cluster

• Evaluation function

Raises:

ValueError – If there is a problem with the argument.

References

[1] The Cambridge Cluster Database, D. J. Wales, J. P. K. Doye, A. Dullweber, M. P. Hodges, F. Y. Naumkin F. Calvo, J. Hernández-Rojas and T. F. Middleton, URL http://www-wales.ch.cam.ac.uk/CCD.html.

clinamen2.utils.lennard_jones.create_position_filter(position_bounds, exception=<class 'BaseException'>)

Create function to filter configurations.

Parameters:

• position_bounds (numpy.typing.ArrayLike) – Positions components that may not be crossed. Shape is (3, 2): 3 components, lower and upper bound for each.

• exception (Exception) – Exception identifying an issue with the calculation.

Return type:

Callable

clinamen2.utils.lennard_jones.get_max_span_from_lj_cluster(lj_cluster, verbose=False)

Evaluate LJ cluster positions and return largest span.

Parameters:

lj_cluster (numpy.typing.ArrayLike) – Positions of the LJ spheres.

Return type:

float

clinamen2.utils.lennard_jones.lj_argparse()

Argument parser for LJ evolution scripts.

Returns

Parsed arguments

clinamen2.utils.neuralil_evaluation module

clinamen2.utils.plot_functions module

Plot functions for CMA-ES results.

class clinamen2.utils.plot_functions.CMAPlotHelper(label, input_dir, generation_bounds, output_dir=None, figsize=(10, 8), colors={'dark_area': '#3e4989', 'dark_line': '#440154', 'highlight': '#fde725', 'light_area': '#b5de2b', 'light_line': '#6ece58', 'medium_area': '#1f9e89', 'medium_line': '#31688e'}, fontsizes={'ax_label': 28, 'legend': 24, 'tick_param': 24, 'title': 36}, json=True)

Bases: object

Setup figure parameters and plot common results.

Parameters:

• label (str) – Label identifying the evolution and its results.

• input_dir (Path) – Directory to read data from.

• handler – Object to access the stored evolution and generations.

• generation_bounds (Tuple[int, int]) – First and last generation to include. Count starts at 1, because generation 0 is the founder. If generation_bounds[1] is passed in with value -1, the last generation is read from the evolution element “last_gen” if present.

• losses – Loss of all read individuals.

• generations – Indices of all read generations.

• step_sizes – Step size of AlgorithmState.

• output_dir (Optional[Path]) – Directory to save files to. Will be created if it does not exist. Default is None.

• information_list – List of dictionaries with additional information per generation.

• additional_info_types – Contains keys identifying additional information and the corresponding types as values for all additional information that is of type numpy.ndarray, list of Numbers or Number.

• figsize (Tuple[float, float]) – Default figure size to be used when no alternative is passed to a plotting function.

• colors (dict) – Dictionary of colors to be used in the plots.

• fontsizes (dict) – Dictionary of fontsizes to be used in the plots.

classify_additional_information()

Parse additional information and classify.

get_data_from_generations()

Parse generations with handler and return data.

plot_additional_information_per_generation(key=None, ax=None, generation_bounds=None, figsize=None, y_units='', save_fig=False, fig_type='pdf')

Plot additional information depending on its type.

Parameters:

• key (Optional[str]) – Key that identifies the additional information. Supercedes index if both given. Default is None.

• ax (Optional[Axis]) – Main ax of figure. To be twinned if present. Default is None.

• generation_bounds (Optional[Tuple[int, int]]) – First and last generation to include. Count starts at 1, because generation 0 is the founder.

• figsize (Optional[Tuple[float, float]]) – Default figure size to be used when no alternative is passed to a plotting function.

• y_units (str) – Units of loss to be added to y_label. Default is empty string.

• save_fig (bool) – If True the figure will be saved to file. Default is False.

• fig_type (str) – File type to be saved. Default is ‘pdf’.

Returns:

Label for plot legend.

Return type:

Optional

plot_additional_per_individual(key=None, generation_bounds=None, figsize=None, y_units='', show_legend=True, ref_val=None, kwargs=None, save_fig=False, fig_type='pdf')

Plot additional info per individual per generation.

Parameters:

• key (Optional[str]) – Key that identifies the additional information. Supercedes index if both given. Default is None.

• generations – Number of generations to be included.

• generation_bounds (Optional[Tuple[int, int]]) – First and last generation to include. Count starts at 1, because generation 0 is the founder.

• figsize (Optional[Tuple[float, float]]) – Default figure size to be used when no alternative is passed to a plotting function.

• show_legend (bool) – If True, plot a legend. Default is True.

• ref_val (Optional[float]) – Value to be plotted as a reference line. Default is None.

• y_units (str) – Units of loss to be added to y_label. Default is empty string.

• save_fig (bool) – If True the figure will be saved to file. Default is False.

• fig_type (str) – File type to be saved. Default is ‘pdf’.

• kwargs (Optional[dict]) – Dicitionary with additional keywords.

Return type:

None

plot_loss_boxplots(generations, figsize=None, y_units='', color_by_key=False, color_key='', save_fig=False, fig_type='pdf')

Plot loss of gen.

Parameters:

• generations (list) – Index of generations to be plotted. More than five will not produce a satisfactory result.

• figsize (Optional[Tuple[float, float]]) – Default figure size to be used when no alternative is passed to a plotting function.

• y_units (str) – Units of loss to be added to y_label. Default is empty string.

• color_key (str) – If True, the scatter plot will be colored according to the data in ‘key’. Default is False.

• save_fig (bool) – If True the figure will be saved to file. Default is False.

• fig_type (str) – File type to be saved. Default is ‘pdf’.

• color_by_key (bool)

Return type:

None

plot_loss_per_generation(generation_bounds=None, figsize=None, y_units='', y_lim=None, show_legend=True, ref_val=None, kwargs=None, save_fig=False, fig_type='pdf')

Plot loss per individual per generation.

Parameters:

• generations – Number of generations to be included.

• generation_bounds (Optional[Tuple[int, int]]) – First and last generation to include. Count starts at 1, because generation 0 is the founder.

• figsize (Optional[Tuple[float, float]]) – Default figure size to be used when no alternative is passed to a plotting function.

• show_legend (bool) – If True, plot a legend. Default is True.

• ref_val (Optional[float]) – Value to be plotted as a reference line. Default is None.

• y_units (str) – Units of loss to be added to y_label. Default is empty string.

• y_lim (Optional[Tuple[float, float]]) – Limit to restrict y axis. Default is None.

• save_fig (bool) – If True the figure will be saved to file. Default is False.

• fig_type (str) – File type to be saved. Default is ‘pdf’.

• kwargs (Optional[dict]) – Dicitionary with additional keywords.

Return type:

None

plot_loss_with_errorbars(generation, key, figsize=None, errorbars=True, y_units='', save_fig=False, fig_type='pdf')

Plot loss of gen.

Parameters:

• generation (int) – Index of generation.

• key (str) – Identifies the additional information to be plotted.

• figsize (Optional[Tuple[float, float]]) – Default figure size to be used when no alternative is passed to a plotting function.

• errorbars (bool) – If True, errorbars are plotted.

• y_units (str) – Units of loss to be added to y_label.Default is empty string.

• save_fig (bool) – If True the figure will be saved to file. Default is False.

• fig_type (str) – File type to be saved. Default is ‘pdf’.

Return type:

None

plot_mean_loss_per_generation(generation_bounds=None, figsize=None, show_sigma_e=True, sigma_e_mult=3, show_min_e=False, show_sigma=False, show_legend=True, y_units='', y_lim=None, ref_val=None, save_fig=False, fig_type='pdf')

Plot mean loss per generation.

Parameters:

• generations – Number of generations to be included.

• generation_bounds (Optional[Tuple[int, int]]) – First and last generation to include. Count starts at 1, because generation 0 is the founder.

• figsize (Optional[Tuple[float, float]]) – Default figure size to be used when no alternative is passed to a plotting function.

• show_sigma_e (bool) – If True, sigma_e_mult * std deviation is plotted additionally around the mean. Default is True.

• sigma_e_mult (int) – If sigma_e is shown, this defines the width.

• show_min_e (bool) – If True, the minimum loss within each generation will be plotted. Default is False.

• show_sigma (bool) – If True, plot step size on axis y2. Default is False.

• show_legend (bool) – If True, plot a legend. Default is True.

• y_units (str) – Units of loss to be added to y_label. Default is empty string.

• y_lim (Optional[Tuple[float]]) – Tuple of y_min and y_max to restrict the plot. Default is None.

• ref_val (Optional[float]) – Value to be plotted as a reference line. Default is None.

• save_fig (bool) – If True the figure will be saved to file. Default is False.

• fig_type (str) – File type to be saved. Default is ‘pdf’.

Return type:

None

plot_stepsize_ax2(ax, x, selected_generations, y_units='')

Plot stepsize as twin of given axis.

Parameters:

• ax (Axis) – Main ax of figure. To be twinned.

• x (numpy.typing.ArrayLike) – Values for x-axis.

• selected_generations (numpy.typing.ArrayLike) – Generations to be plotted.

• y_units (str) – Units of loss to be added to y_label. Default is r’ / si{ngstrom}’.

Return type:

Axis

clinamen2.utils.script_functions module

Reusable code for Python script calls.

clinamen2.utils.script_functions.cma_parser()

Argument parser for example scripts.

Has the CMA-ES parameters as attributes.

Further arguments added to this base parser may not have a shortcut.

Return type:

ArgumentParser

Returns

parser

clinamen2.utils.script_functions.cma_setup(mean, step_size, run_seed=0, pop_size=None, initial_cholesky_factor=None)

Helper function to initialize the algorithm

Return type:

Tuple[AlgorithmParameters, AlgorithmState, numpy.typing.ArrayLike]

clinamen2.utils.script_functions.generate_result_figures(label, input_dir, generation_bounds, output_dir=None, figsize=(10, 8), y_units='', json=True)

Create two default figures for given evolution.

• CMA_PlotHandler.plot_mean_loss_per_generation()

• CMA_PlotHandler.plot_loss_per_generation()

Parameters:

• label (str) – Label of the evolution run.

• input_dir (Path) – Full path to the generated data.

• generation_bounds (Tuple[int, int]) – Plot data between these generations.

• output_dir (Optional[Path]) – Full path to save figures to. DEfaults to input_dir.

• figsize (Tuple[float, float]) – Matpplotlib figure size. Default is (10, 8).

• y_units (str) – Units of loss. Default is empty string.

• json (bool) – Data is stored in JSON files.

Return type:

None

clinamen2.utils.structure_setup module

Reusable code for ASE structure setup and ASE related functions.

Meant to offer simple versions of reusable functions and a possible starting point / template for more complex applications.

class clinamen2.utils.structure_setup.AnchorToImmutable(immutable_atoms, sort_atoms=False)

Bases: object

Class that appends immutable atoms to an atoms object.

Parameters:

• immutable_atoms (Atoms) – Atoms that always have to be added to complete the transformation of a CMA-ES sample to an atoms object to perform calculations on.

• sort_atoms (bool) – If True, ase.build.sort() will be applied to the resulting atoms object.

class clinamen2.utils.structure_setup.DofPipeline(anchor_to_immutable=None, dof_to_atoms=None, apply_weights=None)

Bases: NamedTuple

Functions to be applied to CMA samples in reverse order.

Parameters:

• anchor_to_immutable (Callable) – Combine dof atoms with immutable atoms. Default is None, None function will be skipped.

• dof_to_atoms (Callable) – Construct an atoms object from a CMA-ES sample. Default is None, None function will be skipped.

• apply_weights (Callable) – Dampen or amplify variation of variables in CMA degrees of freedem vector. Default is None, None function will be skipped.

anchor_to_immutable: Callable

Alias for field number 0

apply_weights: Callable

Alias for field number 2

dof_to_atoms: Callable

Alias for field number 1

class clinamen2.utils.structure_setup.DofToAtoms(template_atoms)

Bases: object

Class that creates an atoms object from a compatible CMA-ES sample.

The degrees of freedom making up the sample are translated into the positions of atoms.

Parameters:

template_atoms (Atoms) – Template of an atoms object.

class clinamen2.utils.structure_setup.FilterEvalWorkflow(filter=None, evaluate_loss=None)

Bases: NamedTuple

Evaluation and filter.

Parameters:

• filter (Callable) – Function that filters (marks) results to be omitted.

• evaluate_loss (Callable) – Function that calculates the loss from input.

evaluate_loss: Callable

Alias for field number 1

filter: Callable

Alias for field number 0

clinamen2.utils.structure_setup.bias_covariance_matrix_gauss(atoms, scaled_position, c_r, sigma_cov, dimension)

Return Cholesky factor of biased covariance matrix.

Use Gaussian for decay.

Parameters:

• atoms (Atoms) – Input structure.

• scaled_positions – Positions to compare to (in [0, 1]).

• c_r (float) – Overall bias weight parameter.

• sigma_cov (float) – Gaussian weight parameter.

• dimension (int) – Dimension of the input problem.

• scaled_position (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

Return type:

numpy.typing.ArrayLike

clinamen2.utils.structure_setup.bias_covariance_matrix_r(atoms, scaled_position, c_r, dimension)

Return Cholesky factor of biased covariance matrix.

Parameters:

• atoms (Atoms) – Input structure.

• scaled_positions – Positions to compare to (in [0, 1]).

• c_r (float) – Overall bias weight parameter.

• dimension (int) – Dimension of the input problem.

• scaled_position (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

Return type:

numpy.typing.ArrayLike

Ref:

[1] M. Arrigoni et al., npj Comput. Mater., 2021, 7, 1-13.

clinamen2.utils.structure_setup.create_apply_weights(weights)

Closure to create the apply_weights() function.

Parameters:

weights (numpy.typing.ArrayLike) – Vector of floats to be applied to a CMA-ES sample by multiplication.

Return type:

Callable

Returns:

Function that applies the given weights to a numpy array.

clinamen2.utils.structure_setup.create_filter_eval_workflow(workflow)

Create evaluation workflow with uncertainty.

Parameters:

workflow (FilterEvalWorkflow) – Workflow to create closure from.

Return type:

Callable

clinamen2.utils.structure_setup.create_split_atom(sorted_elements)

Translate ase.atoms.Atoms object to NeuralIL input.

That is, positions, types and cell.

Parameters:

sorted_elements (list) – Input for symbol_map setup.

Return type:

Callable

clinamen2.utils.structure_setup.create_transform_dof(pipeline)

Closure to create a composite function from DofPipeline.

Parameters:

pipeline (NamedTuple) – Named tuple containing the functions to be applied in reverse order.

Return type:

Callable

clinamen2.utils.structure_setup.dir_context(dir_name)

Create a context to run code in a different directory.

Parameters:

dir_name (Path) – Route to the directory.

clinamen2.utils.structure_setup.get_distances_from_position(atoms, position)

Get distances to position in Angstrom.

Parameters:

• atoms (Atoms) – Atoms object to calculate distances for.

• position (Tuple[float, float, float]) – Position to calculate distance from.

clinamen2.utils.structure_setup.get_distances_from_scaled_position(atoms, scaled_position)

Wrapper for get_distances_from_position().

Parameters:

• atoms (Atoms) – Atoms object to calculate distances for.

• scaled_position (Tuple[float, float, float]) – Position to calculate distance from.

clinamen2.utils.structure_setup.place_atoms_packmol(n_atoms=38, side_length=5.0, tolerance=1.0, exec_string=None, random_seed=-1)

Place atoms within a volume utilizing packmol.

Packmol is started as subprocess with limited error handling. For a detailed description see packmol documentation. Input file is created from a jinja2 template.

Parameters:

• n_atoms (int) – Number of atoms to be placed.

• side_length (float) – Atoms are placed within a cube of this side length.

• tolerance (float) – Packmol parameter tolerance (interatomic distance).

• exec_string (Optional[str]) – Packmol executable with full path.

• random_seed (int) – Seed for packmol input. Default is -1, which leads to packmol generating a random seed.

References

[1]: L. Martínez, R. Andrade, E. G. Birgin, J. M. Martínez. J. Comput. Chem., 30(13):2157-2164, 2009.

clinamen2.utils.structure_setup.place_atoms_random_cube(n_atoms=38, side_length=8.0, random_seed=0)

Place atoms randomly within a cube of a given size.

The cube is always centered on zero.

Parameters:

• n_atoms (int) – Number of atoms to be placed.

• side_length (float) – Side length of the cube.

• random_seed (int) – Seed for the random number generator. Default is 0.

clinamen2.utils.structure_setup.place_atoms_random_sphere(n_atoms=38, radius=3.5, random_seed=0)

Place atoms randomly within a sphere of a given radius.

The sphere is always centered at zero.

Parameters:

• n_atoms (int) – Number of atoms to be placed.

• radius (float) – Radius of the sphere.

• random_seed (int) – Seed for the random number generator. Default is 0.

clinamen2.utils.structure_setup.prepare_dof_and_pipeline(founder, scaled_center=None, radius=None)

Get dof vector and pipeline for reconstruction.

The atoms that are accessible by the algorithm can be defined by a sphere.

Parameters:

• founder (Path) – Full path to founder POSCAR.

• scaled_center (Optional[Tuple[float, float, float]]) – Center point of dof sphere, in scaled coordinates.

• radius (Optional[float]) – Radius of dof sphere.

Return type:

numpy.typing.ArrayLike

Module contents

Copyright 2023-2025 The Clinamen2 contributors

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.