Core

class directupsampling.grid.Grid(points: Iterable[Iterable[float] | None] | None = None, axes: tuple[str, ...] | None=None, comm: DummyMPI = <directupsampling.parallel.MPI object>)

Bases: object

Grid representation.

classmethod from_any(grid: Grid | Iterable[tuple[float] | Iterable[float] | None], axes: tuple[str, ...] | str | None = None, comm: DummyMPI = <directupsampling.parallel.MPI object>) → Grid

Return a Grid instance, handling different input formats.

Parameters

gridGrid or list of tuples of floats

A list with the coordinates. Can contain None values instead of tuples, which will yield None during iteration. Can also be a Grid instance, in which case it is returned directly. Can also be a list of floats/ints, which will be converted to a list of single-element tuples.

axestuple[str] or str

Names of the active coordinates.

comm

MPI communicator.

Returns

Grid

The created Grid instance. If grid is already a Grid instance, it is returned directly.

iscatter() → Iterator

class directupsampling.grid.GridPoint(volume: float | None = None, temperature: float | None = None, pressure: float | None = None, lambda_: float | None = None)

Bases: object

A single point on a Grid. Inactive axes are None.

lambda_: float | None = None

pressure: float | None = None

temperature: float | None = None

todict() → dict[str, float]

Return only the active (non-None) fields.

Returns

dict[str, float]

volume: float | None = None

class directupsampling.snapshots.container.SnapshotContainer(index_names: Iterable[str], index: Iterable[tuple] = [], data: list[dict] | None = None, *, replace: bool = False)

Bases: object

Container for snapshots of atoms and their properties.

It is indexed by a flexible multi-field index.

property data: list[dict]

List of the data dicts, one per snapshot.

discard_indices(indices: Iterable[IndexPoint]) → None

Remove entries by index, silently ignoring missing ones.

Parameters

indicesiterable of IndexPoint

Indices to remove.

extend(other: SnapshotContainer, fill_index: list | None = None) → None

Extend this instance from another SnapshotContainer.

extend_from_db(file: str | pathlib.Path) → None

Extend this instance from an ASE .db file.

Parameters

file: str or Path-like

The database to read from.

Notes

Correspondingly to write(), the database volume_per_atom key is set to index volume in the resulting SnapshotContainer.

filter(expr: str) → SnapshotContainer

Return a new SnapshotContainer with entries matching expr.

Parameters

exprstr

Expression string, e.g. 'volume > 15' or 'volume == 12.0 & temperature == 800'.

Returns

SnapshotContainer

classmethod from_list(list_of_atoms: list[Atoms]) → SnapshotContainer

Create a SnapshotContainer from a list of atoms.

The atoms must either have a .calc attribute, or .energy, .forces, .stress. This is mainly a legacy method for training with MLPTrainer and mlippy.

Parameters

list_of_atoms: list of Atoms

List of Atoms objects to create the SnapshotContainer from.

Returns

SnapshotContainer

gather_container(comm: DummyMPI = <directupsampling.parallel.MPI object>) → SnapshotContainer

Gather snapshots from all MPI ranks into this instance on all ranks.

Parameters

commDummyMPI, optional

MPI communicator. Defaults to the global world communicator.

Returns

SnapshotContainer

Self, now containing all snapshots from all ranks.

get(key: str) → ndarray | list

Return all values stored under key, as an array if numeric.

Parameters

keystr

Data field name, e.g. 'electronic_free_energy'.

Returns

numpy.ndarray

If every stored value is numeric.

list

Otherwise.

insert(index: dict[str, float] | Iterable[float] | IndexPoint, **data_entries: Any) → IndexPoint

Insert or update a single row.

Parameters

indexdict, iterable, or IndexPoint

Index identifying the row. Accepted forms:

• mapping of field name → value

• iterable of values in index_names order

• an existing IndexPoint

**data_entries

Data fields to store. Keys must not overlap with index field names.

Returns

IndexPoint

The coerced index that was inserted.

Raises

RuntimeError

If the index already exists and replace=False.

ValueError

If a data key conflicts with an index field name.

classmethod read(file: str | pathlib.Path) → SnapshotContainer

Read in a SnapshotContainer from an ASE database.

The database must contain a __snapshot_container_index__ data entry.

Parameters

file: str or Path-like

The database to read from.

Returns

SnapshotContainer

set_index_defaults(**defaults: Any) → None

Set default values for index fields.

Parameters

**defaults

Keyword arguments with default values for the index fields. The keys must be in index_names.

to_pandas() → Any

Convert the SnapshotContainer to a pandas DataFrame with a MultiIndex.

Returns

pandas.DataFrame

DataFrame with MultiIndex.

Raises

ModuleNotFoundError

If pandas is not installed.

Notes

All indices are casted to float.

write(file: str | pathlib.Path, *, append: bool = True, overwrite: bool = False) → None

Write the SnapshotContainer to an ASE database file.

The index is written to key_value_pairs and works with query and plotting. “volume” is written to “volume_per_atom” to avoid conflict with the ASE special key. For example, to plot the energy vs step for different lambdas at a volume and temperature, use ase db … -p like

>>> ase db database.db 'volume_per_atom=12.0,temperature=800' -s step -p lambda_:step,potential_energy

where -s step is added to plot it sorted on steps.

Parameters

file: str or Path-like

Name of the file to write to

append: bool, default True

If True, appends to the existing database.

overwrite: bool, default False

If True, and append=False, overwrites an existing database.

class directupsampling.snapshots.index.IndexPoint(volume: float | None = None, temperature: float | None = None, pressure: float | None = None, lambda_: float | None = None, seed: int | None = None, step: int | None = None)

Bases: GridPoint

Immutable, hashable, picklable snapshot index.

seed: int | None = None

step: int | None = None

class directupsampling.snapshots.index.IndexView(snapshots: dict[IndexPoint, Any], index_names: tuple[str, ...])

Bases: object

Live view over the index of a SnapshotContainer.

Holds a direct reference to the container’s internal dict so it is always in sync with insertions and deletions without copying.

coerce(index: Any, defaults: dict | None = None) → IndexPoint

Coerce index to an IndexPoint, applying defaults for None fields.

Returns

IndexPoint

Raises

ValueError

If the resulting index fields do not match self.names.

default_grid_names() → list[str]

Return index field names excluding 'seed' and 'step'.

Returns

list[str]

Field names that represent grid axes, in index order.

filter(expr: str) → list[IndexPoint]

Return index points where expr evaluates to true.

Parameters

exprstr

Expression string, e.g. 'volume > 15' or 'volume == 12.0 & temperature == 800'.

Returns

list[IndexPoint]

Matching index points.

get_grid(names: list[str] | None = None) → list[tuple]

Return sorted unique grid points for names.

Parameters

nameslist of str, optional

Index field names to extract. Defaults to all fields except 'seed' and 'step'.

Returns

list[tuple]

Sorted unique combinations of the requested field values.