gnrs.core¶

gnrs.core.task¶

Core task class for all tasks.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.task.TaskABC[source]¶

Bases: ABC

Abstract base class for all tasks.

This class defines the common interface and workflow for tasks like: - Structure generation - Descriptor evaluation - Energy evaluation - Geometry optimization - Clustering and selection

Initialize the task with MPI communicator and settings.

Parameters:

comm – MPI communicator
config – Config dictionary
gnrs_info – Genarris info dictionary

__init__(comm, config, gnrs_info)[source]¶

Initialize the task with MPI communicator and settings.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator
config (dict) – Config dictionary
gnrs_info (dict) – Genarris info dictionary

Return type:

None

run()[source]¶

Execute the complete task workflow.

The workflow consists of: 1. Initialize task 2. Pack settings 3. Print settings 4. Create folders 5. Perform task 6. Collect results 7. Analyze results 8. Finalize task

Return type:: None

abstractmethod initialize(task_name, title)[source]¶

Initialize the task with required setup.

Parameters:

task_name (str) – Name of the task
title (str) – Title to display for the task

Return type:

None

abstractmethod pack_settings()[source]¶

Collect and pack settings needed for the task.

Returns:: Task settings dictionary
Return type:: dict

abstractmethod print_settings(task_set)[source]¶

Print task settings in a formatted table.

Parameters:: task_set (dict) – Task settings dictionary
Return type:: None

abstractmethod create_folders()[source]¶

Create the folder structure required for the task.

Return type:: None

abstractmethod perform_task(task_set)[source]¶

Execute the main task.

Parameters:: task_set (dict) – Task settings dictionary
Return type:: None

abstractmethod collect_results()[source]¶

Collect and save the results of the task.

Return type:: None

abstractmethod analyze()[source]¶

Analyze the results of the task.

Return type:: None

abstractmethod finalize(task_name)[source]¶

Finalize the task and update runtime settings.

Parameters:: task_name (str) – Name of the task
Return type:: None

gnrs.core.energy¶

Abstract base class for energy calculators.

This module provides the base class for implementing energy calculators.

It supports a GPU worker/feeder pattern: when running with more MPI ranks than GPUs, only a subset of ranks (workers) load models onto GPUs. The remaining ranks (feeders) send structures to workers via MPI.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.energy.EnergyCalculatorABC[source]¶

Bases: ABC

Abstract base class for energy calculators.

Supports two execution modes: 1. Direct mode (ranks <= GPUs or CPU-only calculators): Every rank loads the model and computes locally.

2. Worker/feeder mode (ranks > GPUs, GPU-based calculators): Worker ranks (one per GPU) load models. Feeder ranks send structures to their assigned worker and receive results back.

Initialize the energy calculations.

Parameters:

comm – MPI communicator
task_settings – Task settings
energy_name – Energy name

requires_gpu: bool = False¶

__init__(comm, task_settings, energy_name)[source]¶

Initialize the energy calculations.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator
task_settings (dict) – Task settings
energy_name (str) – Energy name

Return type:

None

property device: str¶: Torch device string for this rank.

run(xtal)[source]¶

Run the energy calculation on a single structure (direct mode only).

Parameters:: xtal (ase.Atoms) – Crystal structure
Return type:: None

run_batch(structs, on_structure_done=None)[source]¶

Run energy calculations on a batch of structures.

Parameters:

structs (dict[str, ase.Atoms]) – structure dictionary
on_structure_done (Callable[[], None] | None) – used for checkpoint saves

Return type:

None

abstractmethod initialize()[source]¶

Initialize the energy calculations.

Return type:: None

get_calculator()[source]¶

Returns the calculator.

Return type:: Any

abstractmethod compute(xtal)[source]¶

Compute the energy.

Parameters:: xtal (ase.Atoms) – Crystal structure
Return type:: None

abstractmethod finalize()[source]¶

Finalize the energy calculations.

Return type:: None

gnrs.core.optimizer¶

Abstract base class for geometry optimization.

This module provides the base class for implementing geometry optimization.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.optimizer.GeometryOptimizerABC[source]¶

Bases: ABC

Abstract class for Geometry optimization methods.

All optimizers should inherit this class.

Initialize the geometry optimizer.

Parameters:

comm – MPI communicator for parallel computation
task_set – Optimization settings
opt_name – Optimizer
energy_method – Energy calculation method

__init__(comm, task_set, opt_name='relax', energy_method=None, energy_calc=None)[source]¶

Initialize the geometry optimizer.

Parameters:

comm (MPI.Comm) – MPI communicator for parallel computation
task_set (dict) – Optimization settings
opt_name (str) – Optimizer
energy_method (str | None) – Energy calculation method
energy_calc (any | None)

Return type:

None

run(xtal)[source]¶

Run the optimization workflow.

Initialize
Perform optimization
Update structure information
Finalize

Parameters:: xtal (ase.atoms.Atoms) – ASE Atoms object representing the crystal structure
Return type:: None

initialize()[source]¶

Initialize for optimization.

Return type:: None

abstractmethod optimize(xtal)[source]¶

Perform optimization.

Parameters:: xtal (ase.atoms.Atoms) – ASE Atoms object
Return type:: None

abstractmethod update(xtal)[source]¶

Update the geometry and add energy information.

Parameters:: xtal (ase.atoms.Atoms) – ASE Atoms object
Return type:: None

finalize(xtal)[source]¶

Finalize the optimization and clean up.

Parameters:: xtal (ase.atoms.Atoms) – ASE Atoms object
Return type:: None

gnrs.core.descriptor¶

Abstract base class for crystal structure descriptors.

This module provides the base class for implementing crystal structure descriptors.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.descriptor.DescriptorABC[source]¶

Bases: ABC

Abstract base class for crystal structure descriptors.

This class defines the interface for computing descriptors for crystal structures. All descriptor implementations should inherit from this class and implement the abstract methods.

Initialize the descriptor calculator.

Parameters:

comm – MPI communicator
task_settings – Task settings

__init__(comm, task_settings)[source]¶

Initialize the descriptor calculator.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator
task_settings (dict) – Task settings

Return type:

None

run(xtal)[source]¶

Run the descriptor computation workflow.

Initialize
Compute descriptor
Finalize

Parameters:: xtal (ase.Atoms) – Crystal structure
Return type:: None

abstractmethod initialize()[source]¶

Initialize for descriptor computation.

Return type:: None

abstractmethod compute(xtal)[source]¶

Compute descriptor for a crystal structure.

Parameters:: xtal (ase.Atoms)
Return type:: None

abstractmethod finalize()[source]¶

Return type:: None

gnrs.core.cluster¶

Abstract base class for clustering methods.

This module provides the base class for implementing clustering methods.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.cluster.ClusterABC[source]¶

Bases: ABC

Abstract base class for clustering methods.

This class defines the interface for implementing crystal structure clustering algorithms. All clustering implementations should inherit from this class and implement the abstract methods.

Initialize the clustering method.

Parameters:

comm – MPI communicator
task_settings – Task settings

__init__(comm, task_settings)[source]¶

Initialize the clustering method.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator
task_settings (dict) – Task settings

Return type:

None

run(struct_dict)[source]¶

Run the clustering workflow.

Initialize
Fit the clustering model
Predict clusters
Finalize
Clean up

Parameters:: struct_dict (dict) – Crystal structures
Returns:: Number of clusters found
Return type:: int

cleanup()[source]¶

Remove feature descriptors from xtal.info

Return type:: None

abstractmethod initialize()[source]¶

Initialize for clustering.

Return type:: None

abstractmethod fit()[source]¶

Fit the clustering model to the data.

Return type:: None

abstractmethod predict()[source]¶

Predict clusters for the data.

Returns:: Number of clusters
Return type:: int

abstractmethod finalize()[source]¶

Finalize the clustering process.

Return type:: None

gnrs.core.selection¶

Abstract base class for crystal structure selection.

This module provides the base class for implementing crystal structure selection.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.selection.SelectionABC[source]¶

Bases: ABC

Abstract base class for crystal structure selection algorithms.

This class defines the interface for selecting crystal structures from a pool. All selection implementations should inherit from this class and implement the abstract methods.

Initialize the selection algorithm.

Parameters:

comm – MPI communicator for parallel computation
settings – Selection settings

__init__(comm, settings)[source]¶

Initialize the selection algorithm.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator for parallel computation
settings (dict) – Selection settings

Return type:

None

run(struct_dict)[source]¶

Run the selection workflow.

Initialize
Perform selection
Finalize

Parameters:: struct_dict (dict) – Crystal structures
Return type:: None

abstractmethod initialize()[source]¶

Initialize for selection.

Return type:: None

abstractmethod select(struct_dict)[source]¶

Perform selection on the provided structures.

Parameters:: struct_dict (dict) – Crystal structures
Return type:: None

abstractmethod finalize()[source]¶

Finalize the selection.

Return type:: None

gnrs.core.molecule¶

This module provides functions for handling molecules.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.molecule.Molecule[source]¶

Bases: Atoms

A class inherited from ase for hanlding molecules. probably will NOT be used much.

Initialize the molecule.

Parameters:

*args – Arguments
**kwargs – Keyword arguments

__init__(*args, **kwargs)[source]¶

Initialize the molecule.

Parameters:

*args – Arguments
**kwargs – Keyword arguments

Return type:

None

classmethod read(file_path, *args, **kwargs)[source]¶

Read a molecule from a file.

Parameters:

file_path (str) – File path
*args – Arguments
**kwargs – Keyword arguments

Return type:

Molecule

standardize_orientation()[source]¶

Orient molecule s.t. pricipal axes align with cartesian basis.

Return type:: None

gnrs.core.gpu¶

GPU device management for MPI-parallel workloads.

Implements a worker/feeder pattern where only a subset of MPI ranks (GPU workers) load models onto GPUs, while the remaining ranks (feeders) send structures to workers via MPI for computation. This avoids GPU OOM when running with many MPI ranks and few GPUs.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.gpu.GPUDeviceManager[source]¶

Bases: object

Manages GPU device allocation across MPI ranks.

Partitions ranks into GPU workers and CPU feeders. Workers are assigned to GPUs. Feeders offload computation to workers via MPI.

Typical usage in HPC:

1 GPU node with 1-4 GPUs, 32-128 CPU cores
Workers: 1 per GPU (or configurable)
Feeders: all remaining ranks

Initialize GPU device manager.

Parameters:

comm – MPI communicator.
max_workers_per_gpu – Maximum number of worker ranks per GPU.

__init__(comm, max_workers_per_gpu=1)[source]¶

Initialize GPU device manager.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator.
max_workers_per_gpu (int) – Maximum number of worker ranks per GPU.

Return type:

None

property device: str¶: The torch device string for this rank.

property is_worker: bool¶: Whether this rank is a GPU worker.

property is_feeder: bool¶: Whether this rank is a CPU feeder.

property num_workers: int¶: Total number of GPU worker ranks.

property num_feeders: int¶: Total number of CPU feeder ranks.

property worker_ranks: list[int]¶: List of all worker rank IDs.

property feeder_ranks: list[int]¶: List of all feeder rank IDs.

assigned_worker()[source]¶

Return the worker rank this feeder is assigned to (round-robin).

Returns:: Worker rank ID
Return type:: int

gnrs.core.structure¶

This is the old structure class. Kept for compatibility of PyMoVE.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.structure.StoicDict[source]¶

Bases: defaultdict

get_string()[source]¶

gnrs.core.structure.calc_stoic(geo)[source]¶: returns a dictionary representing the stoichiometries

gnrs.core.structure.get_geo_from_file(file_name)[source]¶: given the path to a geometry-style file, returns the geometry in proper format

gnrs.core.structure.adapt_array(arr)[source]¶

gnrs.core.structure.convert_array(list_of_list)[source]¶: takes the array stored in json format and return it to a np array with proper dtype

gnrs.core.structure.read_data(filepath)[source]¶

class gnrs.core.structure.Structure[source]¶

Bases: object

An optimized structure with relevant information information includes: geometry, energy, stoichiometry, distance array,

Creates a structure from a given geometry and it’s associated properties Properties are stored in a dictionary

__init__()[source]¶

Creates a structure from a given geometry and it’s associated properties Properties are stored in a dictionary

Return type:: None

build_geo_by_atom(x, y, z, element, spin=None, charge=None, fixed=False)[source]¶

THIS METHOD SHOULD JUST BE CALLED APPEND

Return type:: None

append(x, y, z, element, spin=None, charge=None, fixed=False)[source]¶

Return type:: None

build_geo_by_atom_array(x, y, z, element, spin=None, charge=None, fixed=False)[source]¶

These auxillary functions are silly. There should be a single append method that handles all cases of adding a single atom, an array of atoms, etc.

Return type:: None

build_geo_by_whole_atom(atom)[source]¶

Return type:: None

reset_lattice_vectors(vectors)[source]¶

Return type:: None

set_lattice_vectors(vectors)[source]¶

Return type:: None

set_lattice_angles()[source]¶

Return type:: None

from_geo_array(array, elements)[source]¶

Set geometry of structure to the input array and elements

Parameters:

Array (np.matrix of numbers) – Atom coordinates should be stored row-wise
Elements (np.matrix of strings) – Element strings using shorthand notations of same number of rows as the array argument

Return type:

None

add_lattice_vector(vector)[source]¶

Return type:: None

build_geo_whole(geometry)[source]¶

Return type:: None

build_geo_from_atom_file(filepath)[source]¶

Return type:: None

build_struct_from_json_path(filepath)[source]¶

Return type:: None

unpack_geometry(text)[source]¶

Return type:: None

build_geo_whole_atom_format(atom_string)[source]¶

Constructs relevant geometry properties from an FHI-aims geometry: file.

Return type:: None

set_input_ref(input_ref)[source]¶

Return type:: None

set_property(key, value)[source]¶

Return type:: None

delete_property(key)[source]¶

Return type:: None

get_geometry()[source]¶

Return type:: numpy.ndarray

pack_geometry()[source]¶

Return type:: numpy.ndarray

get_n_atoms()[source]¶

Return type:: int

get_n_atoms_per_mol(num_mols)[source]¶

Return type:: int

get_atom_types()[source]¶

Return type:: list[str]

get_input_ref()[source]¶

Return type:: str

get_struct_id()[source]¶

Return type:: str

get_stoic()[source]¶

Return type:: StoicDict

get_stoic_str()[source]¶

Return type:: str

get_path()[source]¶

Return type:: str

get_property(key)[source]¶

get_lattice_vectors()[source]¶

get_lattice_vectors_better()[source]¶: Always returns list as data type

get_geometry_atom_format()[source]¶

Convert structure to FHI-aims geometry format.

Takes a np.ndarray with standard “geometry” format. Returns a string with structure in standard aims format. If atom’s spin is specified, its value is located on the line below the atom’s coordinates. Similarly with charge and relaxation constraint.

Modified to handle molecules without lattice vectors.

get_aims()[source]¶

get_geo_array()[source]¶: Return np.array of (x,y,z) geometry

get_ase_atoms()[source]¶

Works for periodic and non-periodic systems

Purpose: Returns ase atoms object

from_ase(atoms)[source]¶: Loads Structure class from ase atoms object

get_pymatgen_structure()[source]¶: Inputs: A np.ndarry structure with standard “geometry” format Outputs: A pymatgen core structure object with basic geometric properties

get_frac_data()[source]¶: Inputs: A np.ndarry structure with standard “geometry” format Outputs: Fractional coordinate data in the form of positions (list), atom_types (list), lattice vector a magnitude, lattice vector b magnitude, lattice vector c magnitude, alpha beta, gamma.

from_pymatgen(pymatgen_obj)[source]¶: Convert pymatgen Lattice/Molecule to Structure

get_lattice_angles()[source]¶

get_lattice_magnitudes()[source]¶

get_unit_cell_volume()[source]¶

get_atom_distance(a1, a2)[source]¶

angle(v1, v2)[source]¶

document(_id='')[source]¶

Turn Structure object into a document for MongoDB.

Parameters:: _id (str) – The _id for the document in the MongoDB. Default behavior is to use the struct_id as the _id.

dumps()[source]¶

loads(json_string)[source]¶

from_dict(dictionary)[source]¶

gnrs.core.registry¶

Task registry for Genarris.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

gnrs.core.registry.resolve_task(task_name)[source]¶

Resolve a config task name into (task_class, extra_args).

Parameters:: task_name (str) – Task name from the config file.

gnrs.core.folders¶

This module provides functions for managing folder.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

gnrs.core.folders.init_folders(is_master_in)[source]¶

Initialize folder management.

Parameters:: is_master_in (bool)
Return type:: None

gnrs.core.folders.mkdir(dir_path)[source]¶

Create a directory if it doesn’t exist.

Parameters:: dir_path (str)
Return type:: None

gnrs.core.folders.rmdir(dir_path)[source]¶

Remove a directory if it exists.

Parameters:: dir_path (str)
Return type:: None

gnrs.core.folders.setup_main_folders(gnrs_info)[source]¶

Setup Genarris folder structure by creating tmp and structure directories.

Parameters:: gnrs_info (dict)
Return type:: None

gnrs.core.folders.copy_molecule(config, gnrs_info)[source]¶

Copy molecule to tmp directory and standardize orientation.

Parameters:

config (dict)
gnrs_info (dict)

Return type:

None

gnrs.core.logging¶

This module provides functions for logging.

This source code is licensed under the BSD-3-Clause license found in the LICENSE file in the root directory of this source tree.

class gnrs.core.logging.GenarrisLogger[source]¶

Bases: object

Sets up the logging.

Initialize the logger.

Parameters:

comm – MPI communicator
level – Log level
parallel_log – Parallel log mode

__init__(comm, level='DEBUG', parallel_log='redirect_errors')[source]¶

Initialize the logger.

Parameters:

comm (mpi4py.MPI.Comm) – MPI communicator
level (str) – Log level
parallel_log (str) – Parallel log mode

Return type:

None

reset_loglevel(level)[source]¶

Reset the log level.

Parameters:: level (str) – Log level
Return type:: None