ipsuite.bootstrap package

Submodules

ipsuite.bootstrap.random_displacements module

class ipsuite.bootstrap.random_displacements.Bootstrap(*args, **kwargs)[source]

Bases: IPSNode

Base class for dataset bootstrapping with structural modifications.

Parameters

datalist[ase.Atoms]

Input atomic configurations to bootstrap from.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of new configurations to generate.

maximumfloat

Maximum displacement/rotation/translation magnitude.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible generation.

Attributes

frameslist[ase.Atoms]

Generated atomic configurations after bootstrapping.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

bootstrap_configs(atoms: Atoms, rng)[source]
data: list[Atoms]
data_id: int = -1
property frames: list[Atoms]

Load and return the generated atomic configurations.

frames_path: Path = PosixPath('$nwd$/frames.h5')
include_original: bool = True
maximum: float
n_configurations: int
run() → None[source]
seed: int = 0
class ipsuite.bootstrap.random_displacements.RattleAtoms(*args, **kwargs)[source]

Bases: Bootstrap

Generate configurations with randomly displaced atomic positions.

Creates new configurations by applying random displacements to each atom’s position.

Parameters

datalist[ase.Atoms]

Input atomic configurations to modify.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of rattled configurations to generate.

maximumfloat

Maximum displacement magnitude (Ångström) for each atom.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible displacement generation.

Attributes

frameslist[ase.Atoms]

Generated configurations with rattled atomic positions.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

Examples

>>> with project:
...     data = ips.AddData(file="ethanol.xyz")
...     rattled = ips.RattleAtoms(data=data.frames, n_configurations=5, maximum=0.1)
>>> project.repro()
>>> print(f"Generated {len(rattled.frames)} rattled configurations")
Generated 6 rattled configurations
bootstrap_configs(atoms, rng)[source]
class ipsuite.bootstrap.random_displacements.RotateMolecules(*args, **kwargs)[source]

Bases: Bootstrap

Generate configurations with randomly rotated molecular units.

Creates new configurations by applying random rotations to individual molecular units around their barycenter while preserving internal bond structures. Requires distinct molecular entities in the system.

Parameters

datalist[ase.Atoms]

Input atomic configurations containing molecular units.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of configurations with rotated molecules to generate.

maximumfloat

Maximum rotation angle (radians) for each molecule.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible rotation generation.

Attributes

frameslist[ase.Atoms]

Generated configurations with rotated molecular units.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

Examples

>>> with project:
...     data = ips.AddData(file="ethanol.xyz")
...     rotated = ips.RotateMolecules(data=data.frames, n_configurations=5,
...                                  maximum=3.14159)
>>> project.repro()
>>> print(f"Generated {len(rotated.frames)} configurations with rotated molecules")
Generated 6 configurations with rotated molecules
bootstrap_configs(atoms, rng)[source]
class ipsuite.bootstrap.random_displacements.TranslateMolecules(*args, **kwargs)[source]

Bases: Bootstrap

Generate configurations with randomly translated molecular units.

Creates new configurations by applying random translations to individual molecular units while preserving their internal structure. Requires the presence of distinct molecular entities in the system.

Parameters

datalist[ase.Atoms]

Input atomic configurations containing molecular units.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of configurations with translated molecules to generate.

maximumfloat

Maximum translation distance (Ångström) for each molecule.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible translation generation.

Attributes

frameslist[ase.Atoms]

Generated configurations with translated molecular units.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

Examples

>>> with project:
...     data = ips.AddData(file="ethanol.xyz")
...     translated = ips.TranslateMolecules(data=data.frames, n_configurations=5,
...                                        maximum=0.5)
>>> project.repro()
>>> print(f"Generated {len(translated.frames)} configurations with translated "
...       f"molecules")
Generated 6 configurations with translated molecules
bootstrap_configs(atoms, rng)[source]

ipsuite.bootstrap.surface_mods module

class ipsuite.bootstrap.surface_mods.SurfaceRasterMetrics(*args, **kwargs)[source]

Bases: PredictionMetrics

This class analyzes the surface interaction of an additive with a surface. It is used to evaluate how well the surface structure is learned during training. Note that the bulk atoms should not be rattled in the SurfaceRasterScan node.

Attributes

scan_node: SurfaceRasterScan()

The node used for generating the structures

figure_ymax: dict[str, float]
get_plots(save=False)[source]

Create figures for all available data.

scan_node: SurfaceRasterScan
x: list[ase.Atoms]
y: list[ase.Atoms]
class ipsuite.bootstrap.surface_mods.SurfaceRasterScan(*args, **kwargs)[source]

Bases: ProcessSingleAtom

This class generates periodic structures by creating a vacuum slab in the z-direction and adding additives at various positions. It is useful for generating input structures for surface training simulations or in combination with the SurfaceRasterMetrics class to analyze how well surface interactions are captured in the training.

Attributes

symbol: str

ASE symbol representing the additives.

z_dist_list: list[float]

A list of z-distances at which additives will be added.

n_conf_per_dist: list[int]

The number of configurations to generate per z-distance.

cell_fraction: list[float]

Fractional scaling of the unit cell in x and y directions.

random: bool

If True, additives are placed randomly within the specified cell_fraction.

max_rattel_shift: float

Maximum random displacement for each atom.

seed: int

Seed for randomly distributing the additive.

cell_fraction: list[float] = (1, 1)
data: List[ase.Atoms]
max_rattel_shift: float = None
n_conf_per_dist: list[int] = (5, 5)
random: bool = False
run() → None[source]
seed: int = 1
symbol: str
z_dist_list: list[float]
ipsuite.bootstrap.surface_mods.plot_ture_vs_pred(x, y, z, name, height, plots_dir)[source]

Module contents

The Nodes provided by this submodule can be used to create an initial dataset with some structural diversity. This can be useful when starting out from a single configuration and iteratively building datasets with learning on the fly.

class ipsuite.bootstrap.RattleAtoms(*args, **kwargs)[source]

Bases: Bootstrap

Generate configurations with randomly displaced atomic positions.

Creates new configurations by applying random displacements to each atom’s position.

Parameters

datalist[ase.Atoms]

Input atomic configurations to modify.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of rattled configurations to generate.

maximumfloat

Maximum displacement magnitude (Ångström) for each atom.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible displacement generation.

Attributes

frameslist[ase.Atoms]

Generated configurations with rattled atomic positions.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

Examples

>>> with project:
...     data = ips.AddData(file="ethanol.xyz")
...     rattled = ips.RattleAtoms(data=data.frames, n_configurations=5, maximum=0.1)
>>> project.repro()
>>> print(f"Generated {len(rattled.frames)} rattled configurations")
Generated 6 rattled configurations
bootstrap_configs(atoms, rng)[source]
class ipsuite.bootstrap.RotateMolecules(*args, **kwargs)[source]

Bases: Bootstrap

Generate configurations with randomly rotated molecular units.

Creates new configurations by applying random rotations to individual molecular units around their barycenter while preserving internal bond structures. Requires distinct molecular entities in the system.

Parameters

datalist[ase.Atoms]

Input atomic configurations containing molecular units.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of configurations with rotated molecules to generate.

maximumfloat

Maximum rotation angle (radians) for each molecule.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible rotation generation.

Attributes

frameslist[ase.Atoms]

Generated configurations with rotated molecular units.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

Examples

>>> with project:
...     data = ips.AddData(file="ethanol.xyz")
...     rotated = ips.RotateMolecules(data=data.frames, n_configurations=5,
...                                  maximum=3.14159)
>>> project.repro()
>>> print(f"Generated {len(rotated.frames)} configurations with rotated molecules")
Generated 6 configurations with rotated molecules
bootstrap_configs(atoms, rng)[source]
class ipsuite.bootstrap.SurfaceRasterMetrics(*args, **kwargs)[source]

Bases: PredictionMetrics

This class analyzes the surface interaction of an additive with a surface. It is used to evaluate how well the surface structure is learned during training. Note that the bulk atoms should not be rattled in the SurfaceRasterScan node.

Attributes

scan_node: SurfaceRasterScan()

The node used for generating the structures

figure_ymax: dict[str, float]
get_plots(save=False)[source]

Create figures for all available data.

scan_node: SurfaceRasterScan
x: list[ase.Atoms]
y: list[ase.Atoms]
class ipsuite.bootstrap.SurfaceRasterScan(*args, **kwargs)[source]

Bases: ProcessSingleAtom

This class generates periodic structures by creating a vacuum slab in the z-direction and adding additives at various positions. It is useful for generating input structures for surface training simulations or in combination with the SurfaceRasterMetrics class to analyze how well surface interactions are captured in the training.

Attributes

symbol: str

ASE symbol representing the additives.

z_dist_list: list[float]

A list of z-distances at which additives will be added.

n_conf_per_dist: list[int]

The number of configurations to generate per z-distance.

cell_fraction: list[float]

Fractional scaling of the unit cell in x and y directions.

random: bool

If True, additives are placed randomly within the specified cell_fraction.

max_rattel_shift: float

Maximum random displacement for each atom.

seed: int

Seed for randomly distributing the additive.

cell_fraction: list[float] = (1, 1)
data: List[ase.Atoms]
max_rattel_shift: float = None
n_conf_per_dist: list[int] = (5, 5)
random: bool = False
run() → None[source]
seed: int = 1
symbol: str
z_dist_list: list[float]
class ipsuite.bootstrap.TranslateMolecules(*args, **kwargs)[source]

Bases: Bootstrap

Generate configurations with randomly translated molecular units.

Creates new configurations by applying random translations to individual molecular units while preserving their internal structure. Requires the presence of distinct molecular entities in the system.

Parameters

datalist[ase.Atoms]

Input atomic configurations containing molecular units.

data_idint, default=-1

Index of the configuration to use from the data list.

n_configurationsint

Number of configurations with translated molecules to generate.

maximumfloat

Maximum translation distance (Ångström) for each molecule.

include_originalbool, default=True

Whether to include the original configuration in output.

seedint, default=0

Random seed for reproducible translation generation.

Attributes

frameslist[ase.Atoms]

Generated configurations with translated molecular units.

frames_pathPath

Path to the HDF5 file storing the generated configurations.

Examples

>>> with project:
...     data = ips.AddData(file="ethanol.xyz")
...     translated = ips.TranslateMolecules(data=data.frames, n_configurations=5,
...                                        maximum=0.5)
>>> project.repro()
>>> print(f"Generated {len(translated.frames)} configurations with translated "
...       f"molecules")
Generated 6 configurations with translated molecules
bootstrap_configs(atoms, rng)[source]