Generated API from Docstrings

Note

This page is generated during the Sphinx build by scanning the pyar package. Add or update Python docstrings when adding, moving, or refactoring modules; the developer API documentation will then update automatically on the next documentation build.

Aimnet2

pyar.AIMNet2

Molecule

pyar.Molecule

Compatibility shim for the legacy pyar.Molecule module.

Afir

pyar.afir

pyar.afir.restraints

pyar.afir.utils

Shared AFIR helper functions.

pyar.afir.utils.resolve_gamma(value, fallback=100.0)

Return a numeric AFIR gamma value.

The current workflow keeps a backward-compatible fallback so older call sites that do not supply gamma still behave as before.

Aggregate State

pyar.aggregate_state

Compatibility wrapper for pyar.state.aggregate.

Aggregator

pyar.aggregator

Legacy aggregator module.

This module is retained as a compatibility shim. New code should import the workflow entrypoints from pyar.workflows.aggregate and pyar.workflows.solvation.

The shim keeps older imports working while the actual aggregation and solvation implementations live in the workflow package.

pyar.aggregator.aggregate(*args, **kwargs): Deprecated alias for pyar.workflows.aggregate.aggregate().

pyar.aggregator.aggregate_from_formulas(*args, **kwargs): Deprecated alias for pyar.workflows.aggregate.aggregate_from_formulas().

pyar.aggregator.solvate(*args, **kwargs): Deprecated alias for pyar.workflows.solvation.solvate().

pyar.aggregator.add_one(aggregate_id, seeds, monomer, hm_orientations, qc_params, maximum_number_of_seeds, site)

pyar.aggregator.check_for_the_finished_jobs_on_restart(list_of_optimized_molecules, cwd)

pyar.aggregator.check_stop_signal()

pyar.aggregator.expand_formula_to_aggregate_inputs(formula): Convert a formula into aggregate input symbols and multiplicities.

pyar.aggregator.generate_molecule_from_formula(formula, box_size=None, rng=None): Generate a molecule object from a chemical formula.

pyar.aggregator.generate_orientations(num_orientations, mol_id, monomer, seed_counter, seeds, site)

pyar.aggregator.old_path_to_new_path(monomers_to_be_added, old_path)

pyar.aggregator.read_old_path(): Read restart pathway markers from a prior log, if one exists.

pyar.aggregator.read_orientations(molecule_id, noo)

pyar.aggregator.select_pathways(monomers_to_be_added, number_of_pathways)

pyar.aggregator.update_id(aid, the_monomer): Increment one monomer count inside an aggregate identifier.

Backend Capabilities

pyar.backend_capabilities

Backend capability registry for PyAR workflows.

class pyar.backend_capabilities.BackendCapabilities(family='unknown', energy_gradient=False, native_optimization=True, supports_charge=True, supports_multiplicity=True, staged_optimization=False, supported_options=<factory>)

Bases: object

Describe what a backend can do for PyAR workflows.

Parameters:

family (str)
energy_gradient (bool)
native_optimization (bool)
supports_charge (bool)
supports_multiplicity (bool)
staged_optimization (bool)
supported_options (FrozenSet[str])

family: str = 'unknown'

energy_gradient: bool = False

native_optimization: bool = True

supports_charge: bool = True

supports_multiplicity: bool = True

staged_optimization: bool = False

supported_options: FrozenSet[str]

pyar.backend_capabilities.register_backend_capabilities(software, capabilities): Register or replace capability metadata for a backend.

pyar.backend_capabilities.backend_family(software): Return the backend family label.

pyar.backend_capabilities.backend_supports_staged_optimization(software): Return True when the backend has wired loose/normal staged optimization.

pyar.backend_capabilities.get_backend_capabilities(software): Return the capability profile for a backend, if known.

pyar.backend_capabilities.backend_supports_geometry_optimization(software): Return True when geomeTRIC can resolve an energy-gradient provider.

pyar.backend_capabilities.supported_geometry_backends(): Return the list of backends currently allowed on the AFIR/geomeTRIC path.

pyar.backend_capabilities.unsupported_qc_options(software, provided_options): Return explicitly provided QC options that are not supported by a backend.

Backends

pyar.backends

Shared backend helpers and public re-exports for PyAR.

class pyar.backends.SF(molecule)

Bases: object

Base state for PyAR interface workflows that write XYZ files.

pyar.backends.require_executable(program, friendly_name=None): Return an executable path or raise a clear FileNotFoundError.

pyar.backends.which(program): Return the absolute path to an executable if it exists on PATH.

pyar.backends.write_xyz(atoms_list, coordinates, filename, job_name='no_name', energy=0.0): Write a simple XYZ file with an optional energy label.

pyar.backends.run_command(command, stdout_path=None, stderr_path=None, stdin_path=None)

Run a command and return its exit status.

When stdout and stderr should go to the same file, pass the same path for both arguments.

pyar.backends.run_output(command, stderr_path=None)

Run a command and return its stdout bytes.

Raises:: subprocess.CalledProcessError – If the command exits with a non-zero status.

Biases

pyar.biases

Bias potential helpers.

pyar.biases.afir

pyar.biases.afir.get_covalent_radius(z)

Parameters:: z (str) – Atomic Symbol
Returns:: covalent radii

pyar.biases.afir.get_data_structure(atoms, max_cycles)

pyar.biases.afir.isotropic(fragment_indices, atoms_list, coordinates, force)

pyar.biases.afir.main()

Cli

pyar.cli

Command-line entrypoint for PyAR.

pyar.cli.argument_parse(argv=None)

pyar.cli.main()

Core

pyar.core

Core domain entrypoints for the target package layout.

class pyar.core.Molecule(atoms_list, coordinates, name=None, title=None, fragments=None, charge=0, multiplicity=1, scftype='rhf', energy=None)

Bases: object

Domain object for a molecular geometry and its workflow metadata.

property coordinates: numpy.ndarray | None: Cartesian coordinates in Angstrom, or None after failure.

property centroid: numpy.ndarray | None: Return the current geometry centroid, if coordinates exist.

merged_with(other): Return a molecule containing this molecule and other as fragments.

copy(): Return a deep copy preserving workflow metadata.

classmethod from_xyz(filename): Create a molecule from an XYZ file.

split_coordinates(coordinates=None): Return coordinate blocks for each fragment.

split_atoms_lists(): Return atom-symbol blocks for each fragment.

split_covalent_radii_list(): Return covalent-radius blocks for each fragment.

mol_to_xyz(file_name): Write the molecule to an XYZ file.

mol_to_turbomole_coord(): Write the geometry in Turbomole coord format.

is_bonded(bond_scale=1.3): Return whether any inter-fragment pair forms a covalent bond.

property moments_of_inertia_tensor: Return the inertia tensor without mutating the molecule.

rotate_3d(angles): Rotate the molecule in place using Z-X-Z’ Euler angles.

move_to_origin(): Shift the molecule so its centroid lies at the origin.

move_to_centre_of_mass(): Shift the molecule so its center of mass lies at the origin.

translate(magnitude): Translate the molecule in place by magnitude.

align(): Align the molecule with its principal axes in place.

translated(magnitude): Return a translated copy of the molecule.

rotated_3d(angles): Return a rotated copy of the molecule.

aligned(): Return an aligned copy of the molecule.

moved_to_origin(): Return a copy shifted so its centroid lies at the origin.

moved_to_centre_of_mass(): Return a copy shifted so its center of mass lies at the origin.

to_ase_atoms(): Convert this molecule into an ASE Atoms object.

classmethod from_ase_atoms(atoms, name=None, title=None, charge=0, multiplicity=1, scftype='rhf', energy=None): Create a molecule from an ASE Atoms object.

exception pyar.core.XYZParseError

Bases: ValueError

Raised when an XYZ file cannot be parsed.

pyar.core.parse_xyz(filename)

Parse an XYZ file without terminating the process on invalid input.

Parameters:: filename (str)
Return type:: Tuple[list, numpy.ndarray, str, str, float | None]

pyar.core.read_xyz(filename): Read an XYZ file using the historical exit-on-error behavior.

pyar.core.geometry

Geometry helpers for pyar.core.molecule.

pyar.core.geometry.rotation_matrix(angles)

Build the Z-X-Z’ Euler rotation matrix for angles.

Return type:: numpy.ndarray

pyar.core.geometry.moments_of_inertia_tensor(molecule): Return a molecule’s mass-weighted moment-of-inertia tensor.

pyar.core.geometry.translate(molecule, magnitude): Translate molecule in place and return it.

pyar.core.geometry.move_to_origin(molecule): Move molecule to its geometric centroid in place.

pyar.core.geometry.move_to_centre_of_mass(molecule): Move molecule to its center of mass in place.

pyar.core.geometry.rotate_3d(molecule, angles): Rotate molecule about its centroid in place.

pyar.core.geometry.align(molecule): Align molecule to its principal axes in place.

pyar.core.molecule

PyAR Molecule object in the target package layout.

This module defines Molecule, a lightweight domain object used throughout PyAR. It is intentionally small and dependency-light.

Compatibility notes

PyAR has historically treated XYZ parsing errors as fatal and exited the process. That behavior is preserved by read_xyz(). New code should prefer the exception-based parse_xyz() helper for improved testability.

pyar.core.molecule.parse_xyz(filename)

Parse an XYZ file without terminating the process on invalid input.

Parameters:: filename (str)
Return type:: Tuple[list, numpy.ndarray, str, str, float | None]

class pyar.core.molecule.Molecule(atoms_list, coordinates, name=None, title=None, fragments=None, charge=0, multiplicity=1, scftype='rhf', energy=None)

Bases: object

Domain object for a molecular geometry and its workflow metadata.

property coordinates: numpy.ndarray | None: Cartesian coordinates in Angstrom, or None after failure.

property centroid: numpy.ndarray | None: Return the current geometry centroid, if coordinates exist.

merged_with(other): Return a molecule containing this molecule and other as fragments.

copy(): Return a deep copy preserving workflow metadata.

classmethod from_xyz(filename): Create a molecule from an XYZ file.

split_coordinates(coordinates=None): Return coordinate blocks for each fragment.

split_atoms_lists(): Return atom-symbol blocks for each fragment.

split_covalent_radii_list(): Return covalent-radius blocks for each fragment.

mol_to_xyz(file_name): Write the molecule to an XYZ file.

mol_to_turbomole_coord(): Write the geometry in Turbomole coord format.

is_bonded(bond_scale=1.3): Return whether any inter-fragment pair forms a covalent bond.

property moments_of_inertia_tensor: Return the inertia tensor without mutating the molecule.

rotate_3d(angles): Rotate the molecule in place using Z-X-Z’ Euler angles.

move_to_origin(): Shift the molecule so its centroid lies at the origin.

move_to_centre_of_mass(): Shift the molecule so its center of mass lies at the origin.

translate(magnitude): Translate the molecule in place by magnitude.

align(): Align the molecule with its principal axes in place.

translated(magnitude): Return a translated copy of the molecule.

rotated_3d(angles): Return a rotated copy of the molecule.

aligned(): Return an aligned copy of the molecule.

moved_to_origin(): Return a copy shifted so its centroid lies at the origin.

moved_to_centre_of_mass(): Return a copy shifted so its center of mass lies at the origin.

to_ase_atoms(): Convert this molecule into an ASE Atoms object.

classmethod from_ase_atoms(atoms, name=None, title=None, charge=0, multiplicity=1, scftype='rhf', energy=None): Create a molecule from an ASE Atoms object.

pyar.core.molecule.read_xyz(filename): Read an XYZ file using the historical exit-on-error behavior.

pyar.core.molecule.main()

Data

pyar.data

pyar.data.atomic_data

file from ASE

pyar.data.atomic_data.ground_state_magnetic_moments = [0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 2.0, 3.0, 2.0, 1.0, 0.0, 1.0, 0.0, 1.0, 2.0, 3.0, 2.0, 1.0, 0.0, 1.0, 0.0, 1.0, 2.0, 3.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0, 0.0, 1.0, 2.0, 3.0, 2.0, 1.0, 0.0, 1.0, 0.0, 1.0, 2.0, 5.0, 6.0, 5.0, 4.0, 3.0, 0.0, 1.0, 0.0, 1.0, 2.0, 3.0, 2.0, 1.0, 0.0, 1.0, 0.0, 1.0, 1.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 5.0, 4.0, 3.0, 2.0, 1.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 4.0, 3.0, 2.0, 1.0, 0.0, 1.0, 2.0, 3.0, 2.0, 1.0, 0.0, 1.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 5.0, 4.0, 4.0, 2.0, 1.0, 0.0, numpy.nan]

Van der Waals radii in [A] taken from http://www.webelements.com/periodicity/van_der_waals_radius/ and the references given there. Additional source 5 from http://read_total_gradient.wikipedia.org/wiki/Van-der-Waals-Radius

1. Bondi, J. Phys. Chem., 1964, 68, 441.
L. Pauling, The Nature of the Chemical Bond, Cornell University Press, USA, 1945.
J.E. Huheey, E.A. Keiter, and R.L. Keiter in Inorganic Chemistry Principles of Structure and Reactivity, 4th edition, HarperCollins, New York, USA, 1993.W.W. Porterfield in Inorganic chemistry, a unified approach, Addison Wesley Publishing Co., Reading Massachusetts, USA, 1984.
A.M. James and M.P. Lord in Macmillan’s Chemical and Physical Data, Macmillan, London, UK, 1992.
Manjeera Mantina, Adam C. Chamberlin, Rosendo Valero, Christopher J. Cramer, Donald G. Truhlar Consistent van der Waals Radii for the Whole Main Group. In J. Phys. Chem. A. 2009, 113, 5806–5812, doi:10.1021/jp8111556

pyar.data.defualt_parameters

pyar.data.defualt_parameters.values = {'aggregate': False, 'aggregate_size': None, 'basis': 'def2-SVP', 'binary_aggregate': False, 'charge': None, 'custom_keywords': None, 'first_pathway': 0, 'gamma': None, 'geometry_optimizer': 'native', 'gmax': None, 'gmin': None, 'how_many_orientations': 8, 'input_files': [''], 'maximum_number_of_seeds': 8, 'method': 'BP86', 'model': '/scratch/20cy91r19/bitbucket/pyatomgen/pyar/AIMNet2/models/aimnet2_wb97m-d3_ens.jpt', 'multiplicity': None, 'nprocs': 8, 'number_of_pathways': 10, 'opt_cycles': 350, 'opt_target': 'minimum', 'opt_threshold': 'loose', 'react': False, 'scan_bond': None, 'scf_cycles': 1000, 'scf_threshold': 'loose', 'scftype': None, 'site': None, 'size_of_fragment_one': None, 'size_of_fragment_three': None, 'size_of_fragment_two': None, 'software': None, 'ternary_aggregate': False, 'verbosity': 1}: The default calculation parameters

pyar.data.new_atomic_data

pyar.data.units

pyar.data.units.angstrom2bohr(input_value)

pyar.data.units.bohr2angstrom(input_value)

pyar.data.units.kilojoules2atomic_units(input_value)

pyar.data.units.atomic_unit2kilo_calories(input_value)

Data Analysis

pyar.data_analysis

pyar.data_analysis.clustering

pyar.data_analysis.clustering.choose_geometries(list_of_molecules, maximum_number_of_seeds=12, persist_basin_memory=True, apply_basin_memory=True, algorithm=None, group_basin_by_stoichiometry=True)

pyar.data_analysis.clustering.dbscan_clustering(dt)

pyar.data_analysis.clustering.read_energy_from_xyz_file(xyz_file)

pyar.data_analysis.clustering.plot_energy_histogram(molecules)

pyar.data_analysis.clustering.main()

Energy Gradient Providers

pyar.energy_gradient_providers

Energy and gradient providers for geomeTRIC-compatible backends.

class pyar.energy_gradient_providers.EnergyGradientResult(energy_hartree, gradient_hartree_per_bohr)

Bases: object

Backend energy and Cartesian gradient in atomic units.

Parameters:

energy_hartree (float)
gradient_hartree_per_bohr (numpy.ndarray)

energy_hartree: float

gradient_hartree_per_bohr: numpy.ndarray

class pyar.energy_gradient_providers.EnergyGradientProvider(*args, **kwargs)

Bases: Protocol

Provide a backend energy and Cartesian gradient.

evaluate(molecule, coordinates_bohr)

Evaluate the backend objective in Bohr/Hartree units.

Parameters:: coordinates_bohr (numpy.ndarray)
Return type:: EnergyGradientResult

class pyar.energy_gradient_providers.XtbEnergyGradientProvider(qc_params=None)

Bases: object

Evaluate xTB energy and gradient for the current coordinates.

evaluate(molecule, coordinates_bohr)

class pyar.energy_gradient_providers.Aimnet2EnergyGradientProvider(qc_params=None)

Bases: object

Evaluate AIMNet2 energy and gradient for the current coordinates.

evaluate(molecule, coordinates_bohr)

class pyar.energy_gradient_providers.GaussianEnergyGradientProvider(qc_params=None)

Bases: object

Evaluate Gaussian energy and gradient for the current coordinates.

evaluate(molecule, coordinates_bohr): Run one Gaussian force job and parse the resulting gradient.

class pyar.energy_gradient_providers.OrcaEnergyGradientProvider(qc_params=None)

Bases: object

Evaluate ORCA energy and gradient for the current coordinates.

evaluate(molecule, coordinates_bohr): Run one ORCA single-point calculation and parse its gradient.

pyar.energy_gradient_providers.get_energy_gradient_provider(software, qc_params=None): Return the registered energy/gradient provider for a backend.

pyar.energy_gradient_providers.register_energy_gradient_provider(software, provider, capabilities=None): Register or replace an energy/gradient provider for a backend.

File Manager

pyar.file_manager

Handle files and directories in pyar

file_manager.py is part of the pyar project.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

pyar.file_manager.important_file_check(*arguments): Checks if the files given as argument exists

pyar.file_manager.file_exists_check_with_return_status(file_path): This function will check if files in a location exists or not If exists, it will return True else, it will return False.

pyar.file_manager.make_directories(*arguments): This function will generate the directories given as arguments. It will check if the directory exists. If not, it will make the directory. If the directory exists, it will first delete it and make new directory.

pyar.file_manager.delete_files(*arguments): This function will delete files which ar supplied as arguments.

pyar.file_manager.delete_directories(*arguments): This function will delete directories which are provided with arguments if they exists

pyar.file_manager.get_files(extension, destination='./'): This function will return all file names as a list from a directory ‘destination’. By default it is current directory. Extension should be simply “xyz”, “out” , “log” etc.

pyar.file_manager.get_dirs_files(destination='./', wildcard='*'): This function will return all the subdirectory of the parent directory destination. Note, it will use glob. So, will not test for files

pyar.file_manager.move_file(current_file, moved_file, path_to_move): This function will move a file current_file to a destination directory path_to_move with a name moved_file

pyar.file_manager.bulk_move(*args)

Parameters:: args – This is the argument lists. It will take tha last name as the directory name. If any of the files match with the strings it provided, it will move this file to the directory
Returns:: It will return nothing.

pyar.file_manager.bulk_copy(*args)

Parameters:: args – This are the argument lists. It will take the last name as directory name. if any of the files match with the strings it provided, it will copy this files to the directory. Similar to bulk_move function
Returns:: Nothing

pyar.file_manager.write_result(filename, **kwargs): This function will write the results as final files.

pyar.file_manager.check_stop(filename): This function is for checking by presence of a file. If this file present, The program will stop after completion of a cycle. This function is like the ‘STOP’ file concept in turbomole.

pyar.file_manager.main()

Interface

pyar.interface

Compatibility entrypoints for pyar.backends.

class pyar.interface.SF(molecule)

Bases: object

Base state for PyAR interface workflows that write XYZ files.

pyar.interface.require_executable(program, friendly_name=None): Return an executable path or raise a clear FileNotFoundError.

pyar.interface.which(program): Return the absolute path to an executable if it exists on PATH.

pyar.interface.write_xyz(atoms_list, coordinates, filename, job_name='no_name', energy=0.0): Write a simple XYZ file with an optional energy label.

pyar.interface.run_command(command, stdout_path=None, stderr_path=None, stdin_path=None)

Run a command and return its exit status.

When stdout and stderr should go to the same file, pass the same path for both arguments.

pyar.interface.run_output(command, stderr_path=None)

Run a command and return its stdout bytes.

Raises:: subprocess.CalledProcessError – If the command exits with a non-zero status.

Io

pyar.io

I/O entrypoints for the target package layout.

class pyar.io.WorkflowResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: object

Common metadata for workflow outcomes.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

workflow: str

status: str

run_directory: str

state_path: str | None = None

selected_paths: tuple[str, ...] = ()

metadata: Mapping[str, Any]

to_dict(): Return a plain dictionary for logging or serialization.

class pyar.io.AggregateResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for aggregation runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

class pyar.io.SolvationResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for solvation runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

class pyar.io.ReactionResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for reaction runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

pyar.io.results

Compatibility entrypoint for the target pyar.io layout.

pyar.io.xyz

I/O helpers for pyar.core.molecule.

pyar.io.xyz.as_coordinates_array(value)

Validate and return Cartesian coordinates as an (N, 3) array.

Return type:: numpy.ndarray

pyar.io.xyz.validate_fragments(fragments, number_of_atoms)

Validate atom-index fragment definitions for a molecule.

Parameters:: number_of_atoms (int)
Return type:: list

exception pyar.io.xyz.XYZParseError

Bases: ValueError

Raised when an XYZ file cannot be parsed.

pyar.io.xyz.parse_xyz(filename)

Parse an XYZ file and raise XYZParseError on malformed input.

Parameters:: filename (str)
Return type:: Tuple[list, numpy.ndarray, str, str, float | None]

pyar.io.xyz.read_xyz(filename)

Read an XYZ file using PyAR’s historical exit-on-error interface.

Parameters:: filename (str)

pyar.io.xyz.write_xyz(molecule, file_name): Write a molecule and optional energy label in XYZ format.

pyar.io.xyz.write_turbomole_coord(molecule, file_name='coord'): Write a molecule in Turbomole coord format.

Mlatom

pyar.mlatom

Compatibility adapter for the external MLatom package.

Molecule Geometry

pyar.molecule_geometry

Compatibility shim for the legacy pyar.molecule_geometry module.

Molecule Io

pyar.molecule_io

Compatibility shim for the legacy pyar.molecule_io module.

Molecule Merge

pyar.molecule_merge

Merge helpers for pyar.Molecule.

pyar.molecule_merge.combine_multiplicity(first, second)

Preserve the existing heuristic for combined multiplicity.

Return type:: int

pyar.molecule_merge.merged_with(first, second): Return a molecule containing first and second as fragments.

Optimiser

pyar.optimiser

Optimiser Module

Functions

optimise(molecule, qc_params) write_csv(csv_file, energy_dit) bulk_optimize(input_files, qc_params)

pyar.optimiser.is_success(status)

pyar.optimiser.is_cycle_exceeded(status)

pyar.optimiser.is_usable(status)

pyar.optimiser.apply_geometry_result(molecule, geometry)

pyar.optimiser.build_geometry(molecule, qc_params): Create the interface wrapper for a configured software backend.

pyar.optimiser.optimise(molecule, qc_params): Run one optimization job and return the backend status object.

pyar.optimiser.write_csv_file(csv_filename, energy_dict)

pyar.optimiser.bulk_optimize(input_molecules, qc_params): Optimize molecules and keep only usable results.

pyar.optimiser.main()

Optional Dependencies

pyar.optional_dependencies

Helpers for optional dependency error messages.

pyar.optional_dependencies.optional_dependency_error(module_name, feature=None, extra=None): Return an ImportError with a consistent optional-extra install hint.

pyar.optional_dependencies.require_optional(module_name, feature=None, extra=None): Import an optional module or raise a clear extra-specific ImportError.

Orientation Sampling

pyar.orientation_sampling

Compatibility shim for the legacy pyar.orientation_sampling module.

Property

pyar.property

Calculate or retrieve properties of the input molecules.

pyar.property.distance(coords_a, coords_b)

Calculates distance between atoms a and b.

Parameters:

coords_a (ndarray(float)) – Coordinate of atom a
coords_b (ndarray(float)) – Coordinate of atom b

Returns:

The distance between atom a and b

Return type:

float

pyar.property.get_centroid(coordinates)

pyar.property.get_centre_of_mass(coordinates, atomic_mass)

pyar.property.get_average_radius(coordinates, centroid)

pyar.property.get_std_of_radius(coordinates, centroid)

pyar.property.get_principal_axes(moments_of_inertia_tensor)

pyar.property.get_distance_list(coordinates)

pyar.property.get_distance_matrix(coordinates)

pyar.property.get_bond_matrix(coordinates, covalent_radius): return bond matrix

pyar.property.get_connectivity(coordinates, covalent_radius): return connection graph

pyar.property.calculate_angle(a1, b1, c1)

pyar.property.hydrogen_bond_analysis(coordinates, covalent_radius, atomic_number, atoms_list): return bond matrix

pyar.property.calculate_dihedral(p0, p1, p2, p3)

Reaction Analysis

pyar.reaction_analysis

AFIR reaction-path analysis for recorded geomeTRIC traces.

The analysis layer reads the JSONL/XYZ trace emitted by the reaction workflow, writes a CSV summary, exports candidate geometries for the most interesting path points, and can generate standalone plots from the same recorded trace.

pyar.reaction_analysis.analyse_reaction_trace(job_directory)

Write a compact summary and candidate geometries for one reaction path.

job_directory may point either to the workflow root or directly to a reaction_trace/ directory. The function writes path_summary.csv in the job root, exports the candidate XYZ files under candidate_ts/, and returns a metadata dictionary describing the selected points.

pyar.reaction_analysis.plot_reaction_trace(job_directory, output_directory=None)

Create PNG plots from a recorded reaction trace.

The plots summarize the relative energies, bond-change count, inter- fragment distance, and force norms across the recorded steps. When no output directory is supplied, the figures are written to trace_plots/ in the job root.

Reaction Identity

pyar.reaction_identity

Reaction identity helpers for product detection and restart bookkeeping.

pyar.reaction_identity.write_disconnected_reference(molecule, path, separation=100.0): Write an unreacted identity reference with fragments far apart.

pyar.reaction_identity.molecule_identity_from_xyz(xyzfile): Return the OpenBabel identity for an XYZ file.

pyar.reaction_identity.same_molecular_identity(first, second)

Return whether two identities represent the same molecular product.

InChI is used as the stable identity key. SMILES is retained for readable reports, but equivalent products need not serialize to the same SMILES.

Reaction State

pyar.reaction_state

Compatibility wrapper for pyar.state.reaction.

Reaction Trace

pyar.reaction_trace

Reaction-path trace recording for geomeTRIC-backed AFIR optimizations.

The recorder writes a JSONL trace plus per-step XYZ snapshots for each geomeTRIC-backed reaction evaluation. The resulting trace is the input for the analysis and plotting helpers in pyar.reaction_analysis.

pyar.reaction_trace.infer_bonds(symbols, coordinates_angstrom, previous_bonds=None)

Infer a conservative bond set from coordinates and covalent radii.

The heuristic is intentionally cautious: new bonds are only introduced when the interatomic distance is comfortably below the covalent-radius threshold, while previously observed bonds are allowed a wider hysteresis window so small numerical changes do not flicker the bond list.

pyar.reaction_trace.bond_changes(previous_bonds, current_bonds): Return formed and broken bonds between consecutive bond sets.

pyar.reaction_trace.min_interfragment_distance(coordinates_angstrom, fragment_indices)

Return the minimum distance between atoms in distinct fragments.

The value is only computed when at least two non-empty fragments are available. Otherwise the trace record stores None for this field.

pyar.reaction_trace.validate_trace_record(record, record_index)

Validate the structure of one trace record.

The validator enforces the schema used by the analysis and plotting code and returns a normalized record with numeric fields converted to native Python types.

class pyar.reaction_trace.ReactionTraceRecorder(job_directory, trace_name='reaction_trace', mode='write')

Bases: object

Append geomeTRIC evaluation data to JSONL and XYZ trace files.

The recorder is stateful: it tracks the next step index, reconstructs the previous bond set when appending to an existing trace, and keeps the JSONL trace and XYZ snapshots synchronized on disk.

record(*, symbols, coordinates_angstrom, backend_energy_hartree, afir_energy_hartree, total_energy_hartree, backend_forces_hartree_per_bohr, afir_forces_hartree_per_bohr, total_forces_hartree_per_bohr, backend_force_norm, afir_force_norm, total_force_norm, max_force, fragment_indices=None)

Write one trace record and its corresponding XYZ snapshot.

The recorded JSON object includes the raw energies/forces, bond-change counts, and interfragment distance used by the downstream analysis tools. The companion XYZ snapshot preserves the optimized geometry for the same step index.

pyar.reaction_trace.load_trace_records(trace_file)

Load and validate JSONL trace records from trace_file.

trace_file may be either the JSONL file itself or the containing reaction_trace/ directory. Each line is validated and normalized before being returned, so callers can rely on the trace schema.

Reactor

pyar.reactor

Reaction workflow orchestration for PyAR.

This module owns the AFIR reaction-search pipeline:

build the numeric gamma schedule
prepare and persist restartable reaction state
generate trial orientations for each gamma cycle
optimize each orientation with the selected backend
perform unbiased relaxation when a bonded candidate is found
deduplicate and persist unique products
emit trace-analysis summaries for successful paths

The module is the implementation behind the legacy pyar.reactor import path and the pyar-react command-line entry point.

Representations

pyar.representations

pyar.representations.get_rsmd(mol): Molecular Descriptor written by Rajat Shubhro Majumdar

pyar.representations.make_internal_coordinates(mol)

Return type:: list of internal coordinates

pyar.representations.sorted_coulomb_matrix(cm)

From: https://github.com/pythonpanda/coulomb_matrix/ Takes in a Coulomb matrix of (mxn) dimension and performs a row-wise sorting such that ||C(j,:)|| > ||C(j+1,:)||, J= 0,1,…….,(m-1) Finally returns a vectorized (m*n,1) column matrix.

Parameters:: cm (ndarray) – Coulomb matrix

pyar.representations.coulomb_matrix(atoms_list, coordinates)

Returns:: Coulomb Matrix

pyar.representations.fingerprint(atoms_list, coordinates)

pyar.representations.cutoff_func(r, Rc)

pyar.representations.radial_symmetry_func(r, eta, Rs, Rc)

pyar.representations.angular_symmetry_func(r_ij, r_ik, r_jk, theta_ijk, eta, zeta, lambda_, Rc)

pyar.representations.generate_aev(atom_list, coordinates)

pyar.representations.lmbtr_descriptor(atoms_list, coordinates)

pyar.representations.acsf_descriptor(atoms_list, coordinates)

pyar.representations.sinematrix_descriptor(atoms_list, coordinates)

pyar.representations.valleoganov_descriptor(atoms_list, coordinates)

pyar.representations.mbtr_descriptor(atoms_list, coordinates)

pyar.representations.soap_descriptor(atoms_list, coordinates)

pyar.representations.main()

Sampling

pyar.sampling

Sampling entrypoints for the target package layout.

class pyar.sampling.RotationCoverageMetrics(minimum_separation_degrees, mean_nearest_neighbor_degrees, covering_radius_degrees, mean_covering_distance_degrees)

Bases: object

Quality measures for sampled monomer rotations.

Parameters:

minimum_separation_degrees (float)
mean_nearest_neighbor_degrees (float)
covering_radius_degrees (float)
mean_covering_distance_degrees (float)

minimum_separation_degrees: float

mean_nearest_neighbor_degrees: float

covering_radius_degrees: float

mean_covering_distance_degrees: float

class pyar.sampling.SphereCoverageMetrics(minimum_separation_degrees, mean_nearest_neighbor_degrees, covering_radius_degrees, mean_covering_distance_degrees, centroid_norm)

Bases: object

Quality measures for directional sphere samples.

Parameters:

minimum_separation_degrees (float)
mean_nearest_neighbor_degrees (float)
covering_radius_degrees (float)
mean_covering_distance_degrees (float)
centroid_norm (float)

minimum_separation_degrees: float

mean_nearest_neighbor_degrees: float

covering_radius_degrees: float

mean_covering_distance_degrees: float

centroid_norm: float

pyar.sampling.canonicalize_quaternion(quaternion)

Normalize a quaternion and choose a consistent sign representative.

Parameters:: quaternion (numpy.ndarray)
Return type:: numpy.ndarray

pyar.sampling.fibonacci_sphere(number_of_points, offset=0.5, azimuth_offset=0.0)

Generate deterministic approximately uniform directions on a sphere.

Parameters:

number_of_points (int)
offset (float)
azimuth_offset (float)

Return type:

numpy.ndarray

pyar.sampling.generate_directions(method, number_of_points, *, seed=None, sequence_offset=0, oversample_factor=8)

Generate trial-placement directions using a named sampling method.

Parameters:

method (str)
number_of_points (int)
seed (int | None)
sequence_offset (int)
oversample_factor (int)

Return type:

numpy.ndarray

pyar.sampling.generate_trial_vectors(number_of_points, *, direction_method='fibonacci', rotation_method='halton', seed=None, sequence_offset=0, oversample_factor=8, use_angles=True)

Return direction and orientation vectors for trial geometries.

Parameters:

number_of_points (int)
direction_method (str)
rotation_method (str)
seed (int | None)
sequence_offset (int)
oversample_factor (int)
use_angles (bool)

Return type:

numpy.ndarray

pyar.sampling.halton_quaternions(number_of_points, seed=None)

Generate deterministic low-discrepancy unit quaternions.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.latin_hypercube_sphere(number_of_points, seed=None)

Generate sphere directions from a Latin-hypercube sample.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.maximin_select(points, number_of_points)

Select a spread-out subset of candidate directions greedily.

Parameters:

points (numpy.ndarray)
number_of_points (int)

Return type:

numpy.ndarray

pyar.sampling.quaternion_coverage_metrics(quaternions, *, evaluation_points=10000)

Measure angular spread and covering quality for quaternions.

Parameters:

quaternions (numpy.ndarray)
evaluation_points (int)

Return type:

RotationCoverageMetrics

pyar.sampling.quaternions_to_euler_zxz(quaternions)

Convert unit quaternions to Z-X-Z Euler angles in radians.

Parameters:: quaternions (numpy.ndarray)
Return type:: numpy.ndarray

pyar.sampling.random_quaternions(number_of_points, seed=None)

Generate random unit quaternions for monomer rotation sampling.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.random_sphere(number_of_points, seed=None)

Generate uniformly distributed random sphere directions.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.sphere_coverage_metrics(points, *, evaluation_points=10000)

Measure angular spread and covering quality for sphere directions.

Parameters:

points (numpy.ndarray)
evaluation_points (int)

Return type:

SphereCoverageMetrics

pyar.sampling.create_composite_molecule(seed, monomer, points_and_angles, d_scale): Create a composite molecule by applying consecutive placements.

pyar.sampling.create_trial_geometries(molecule_id, seed, monomer, number_of_orientations, site): Generate and write merged trial geometries for one growth operation.

pyar.sampling.generate_points(number_of_orientations, sequence_offset=0): Generate default trial direction and monomer-orientation vectors.

pyar.sampling.merge_two_molecules(vector, seed_input, monomer_input, freeze_fragments=False, site=None, distance_scaling=1.5): Place and merge a monomer around a seed using one trial vector.

pyar.sampling.write_trial_vectors(vectors, output_file): Append generated direction and rotation vectors to an output file.

pyar.sampling.metrics

Coverage metrics for sphere and rotation sampling.

class pyar.sampling.metrics.SphereCoverageMetrics(minimum_separation_degrees, mean_nearest_neighbor_degrees, covering_radius_degrees, mean_covering_distance_degrees, centroid_norm)

Bases: object

Quality measures for directional sphere samples.

Parameters:

minimum_separation_degrees (float)
mean_nearest_neighbor_degrees (float)
covering_radius_degrees (float)
mean_covering_distance_degrees (float)
centroid_norm (float)

minimum_separation_degrees: float

mean_nearest_neighbor_degrees: float

covering_radius_degrees: float

mean_covering_distance_degrees: float

centroid_norm: float

class pyar.sampling.metrics.RotationCoverageMetrics(minimum_separation_degrees, mean_nearest_neighbor_degrees, covering_radius_degrees, mean_covering_distance_degrees)

Bases: object

Quality measures for sampled monomer rotations.

Parameters:

minimum_separation_degrees (float)
mean_nearest_neighbor_degrees (float)
covering_radius_degrees (float)
mean_covering_distance_degrees (float)

minimum_separation_degrees: float

mean_nearest_neighbor_degrees: float

covering_radius_degrees: float

mean_covering_distance_degrees: float

pyar.sampling.metrics.sphere_coverage_metrics(points, *, evaluation_points=10000)

Measure angular spread and covering quality for sphere directions.

Parameters:

points (numpy.ndarray)
evaluation_points (int)

Return type:

SphereCoverageMetrics

pyar.sampling.metrics.quaternion_coverage_metrics(quaternions, *, evaluation_points=10000)

Measure angular spread and covering quality for quaternions.

Parameters:

quaternions (numpy.ndarray)
evaluation_points (int)

Return type:

RotationCoverageMetrics

pyar.sampling.rotation

Rotation sampling helpers for trial placement.

pyar.sampling.rotation.random_quaternions(number_of_points, seed=None)

Generate random unit quaternions for monomer rotation sampling.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.rotation.halton_quaternions(number_of_points, seed=None)

Generate deterministic low-discrepancy unit quaternions.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.rotation.canonicalize_quaternion(quaternion)

Normalize a quaternion and choose a consistent sign representative.

Parameters:: quaternion (numpy.ndarray)
Return type:: numpy.ndarray

pyar.sampling.rotation.quaternions_to_euler_zxz(quaternions)

Convert unit quaternions to Z-X-Z Euler angles in radians.

Parameters:: quaternions (numpy.ndarray)
Return type:: numpy.ndarray

pyar.sampling.sphere

Sphere sampling helpers for trial placement.

pyar.sampling.sphere.fibonacci_sphere(number_of_points, offset=0.5, azimuth_offset=0.0)

Generate deterministic approximately uniform directions on a sphere.

Parameters:

number_of_points (int)
offset (float)
azimuth_offset (float)

Return type:

numpy.ndarray

pyar.sampling.sphere.latin_hypercube_sphere(number_of_points, seed=None)

Generate sphere directions from a Latin-hypercube sample.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.sphere.random_sphere(number_of_points, seed=None)

Generate uniformly distributed random sphere directions.

Parameters:

number_of_points (int)
seed (int | None)

Return type:

numpy.ndarray

pyar.sampling.sphere.maximin_select(points, number_of_points)

Select a spread-out subset of candidate directions greedily.

Parameters:

points (numpy.ndarray)
number_of_points (int)

Return type:

numpy.ndarray

pyar.sampling.sphere.generate_directions(method, number_of_points, *, seed=None, sequence_offset=0, oversample_factor=8)

Generate trial-placement directions using a named sampling method.

Parameters:

method (str)
number_of_points (int)
seed (int | None)
sequence_offset (int)
oversample_factor (int)

Return type:

numpy.ndarray

pyar.sampling.trial_generator

Trial geometry generation and merge helpers.

pyar.sampling.trial_generator.polar_to_cartesian(r, theta, phi): Convert spherical polar coordinates to Cartesian coordinates.

pyar.sampling.trial_generator.check_close_contact(mol_1, mol_2, factor): Return whether two fragments contain a scaled close contact.

pyar.sampling.trial_generator.minimum_separation(mol_1, mol_2): Return the minimum inter-fragment Cartesian separation.

pyar.sampling.trial_generator.merge_two_molecules(vector, seed_input, monomer_input, freeze_fragments=False, site=None, distance_scaling=1.5): Place and merge a monomer around a seed using one trial vector.

pyar.sampling.trial_generator.ellipsoid_wall_potential(coordinates, a, b, c, k=100.0): Return an ellipsoidal wall penalty for coordinates outside the bounds.

pyar.sampling.trial_generator.create_composite_molecule(seed, monomer, points_and_angles, d_scale): Create a composite molecule by applying consecutive placements.

pyar.sampling.trial_generator.spherical_to_cartesian(r, theta, phi): Convert spherical coordinates to a Cartesian vector.

pyar.sampling.trial_generator.generate_trial_vectors(number_of_points, *, direction_method='fibonacci', rotation_method='halton', seed=None, sequence_offset=0, oversample_factor=8, use_angles=True)

Return direction and orientation vectors for trial geometries.

Parameters:

number_of_points (int)
direction_method (str)
rotation_method (str)
seed (int | None)
sequence_offset (int)
oversample_factor (int)
use_angles (bool)

Return type:

numpy.ndarray

pyar.sampling.trial_generator.generate_points(number_of_orientations, sequence_offset=0): Generate default trial direction and monomer-orientation vectors.

pyar.sampling.trial_generator.create_trial_geometries(molecule_id, seed, monomer, number_of_orientations, site): Generate and write merged trial geometries for one growth operation.

pyar.sampling.trial_generator.plot_points(points, location): Plot sampled direction points on a unit sphere.

pyar.sampling.trial_generator.write_trial_vectors(vectors, output_file): Append generated direction and rotation vectors to an output file.

pyar.sampling.trial_generator.main()

pyar.sampling.trial_generator.get_connectivity(coordinates, covalent_radii, tolerance=0.4)

Return covalent-radius-based connectivity edges for a geometry.

Parameters:

coordinates (numpy.ndarray)
covalent_radii (List[float])
tolerance (float)

Return type:

List[Tuple[int, int]]

pyar.sampling.trial_generator.broken(molobj)

Return whether a molecule is disconnected under its covalent-radius graph.

Return type:: bool

Scan

pyar.scan

pyar.scan.generate_guess_for_bonding(molecule_id, seed, monomer, a, b, number_of_orientations, d_scale)

pyar.scan.ab_dist(a, b, monomer, seed, pts)

pyar.scan.generate_guess_for_bonding_brute_force(molecule_id, seed, monomer, a, b, number_of_orientations, d_scale)

pyar.scan.scan_distance(input_molecules, site_atoms, number_of_orientations, quantum_chemistry_parameters)

Scripts

pyar.scripts

Command line arguments in pyar

pyar-cli: the main cli for aggregation and reaction
pyar-clustering: cluster or filter the given molecules based on their similarity with each other.
pyar-energy-table: print a relative-energy table from one or more XYZ files.
pyar-descriptor: compute compact cluster descriptors from XYZ files.
pyar-similarity: detect near-duplicate XYZ structures with the Grigoryan-Springborg metric.
pyar-trial-generation: generate trial geometries and orientation samples.
pyar-optimiser: optimize molecules with a generic backend setting.
pyar-benchmark-clustering: benchmark cluster-selection algorithms.
pyar-benchmark-orientations: benchmark trial-direction samplers.
pyar-reaction-trace: analyze a reaction trace and generate plots.

pyar.scripts.benchmark_clustering

Benchmark clustering/selection algorithms on one or more XYZ pools.

This utility compares the geometry-selection algorithms exposed by pyar.data_analysis.clustering and reports selection quality, diversity, and runtime for one or more pools of XYZ files.

pyar.scripts.benchmark_clustering.main()

pyar.scripts.benchmark_orientations

Benchmark direction samplers used for trial geometry placement.

The benchmark compares the available placement-direction generators used by the trial-geometry code paths and reports sphere-coverage statistics plus runtime.

pyar.scripts.benchmark_orientations.main(): Run reproducible unit-sphere coverage comparisons.

pyar.scripts.clustering

Importable pyar-clustering entrypoint.

This utility clusters or filters XYZ pools using the selection algorithms implemented in pyar.data_analysis.clustering. It prints the energy table for the input pool and then emits the selected geometries.

pyar.scripts.clustering.main(): Cluster or filter the provided XYZ pool and print the selected files.

pyar.scripts.descriptor

Importable pyar-descriptor entrypoint.

This utility computes a compact cluster-shape descriptor for each XYZ file and writes per-structure descriptor files alongside summary CSV output.

pyar.scripts.descriptor.calculate_properties(atoms): Return the basic shape descriptors used to characterize one cluster.

pyar.scripts.descriptor.create_combined_descriptor(properties): Combine the basic descriptors into a single normalized score.

pyar.scripts.descriptor.main(args=None): Compute and write descriptors for one or more XYZ files.

pyar.scripts.energy_table

Importable pyar-energy-table entrypoint.

This utility prints a relative-energy table for one or more XYZ files. It is used as a lightweight inspection tool for comparing geometries without running a full workflow.

pyar.scripts.energy_table.main(): Read XYZ files, attach energies, and print a ranked energy table.

pyar.scripts.explore

Importable pyar-explore entrypoint.

This script generates candidate composite geometries by combining a seed molecule, a monomer, and a formula-derived pathway. It is a convenience driver around the trial-generation and molecule-merging helpers used by the aggregation workflow.

pyar.scripts.explore.parse_arguments(): Parse the pyar-explore command-line arguments.

pyar.scripts.explore.parse_formula(formula): Parse a chemical formula into an ordered atom-count mapping.

pyar.scripts.explore.generate_chemical_pathway(atom_counts, seed): Return the list of atoms that still need to be added to the seed.

pyar.scripts.explore.create_composite_molecule_wrapper(seed, monomer, pathway, sequence_offset=0)

Create one candidate composite geometry for a pathway.

The wrapper seeds the orientation generator with sequence_offset so repeated populations are reproducible while still producing distinct geometry sets.

pyar.scripts.explore.main(): Generate one or more composite geometries from a formula.

pyar.scripts.optimiser

Importable pyar-optimiser entrypoint.

This utility runs the general-purpose geometry optimizer over one or more input structures without going through the aggregation, reaction, or solvation workflow state machines.

pyar.scripts.optimiser.main(): Parse optimizer options, load input molecules, and run bulk optimization.

pyar.scripts.react

Importable pyar-react entrypoint.

This script provides the historical reaction-search command-line interface that wraps pyar.workflows.reaction.react(). It converts CLI arguments into the backend parameter dictionary expected by the workflow and applies the same geometry-optimizer guardrails as the main pyar-cli entrypoint.

pyar.scripts.react.argument_parse(): Parse the reaction-search command-line arguments.

pyar.scripts.react.calculate_index_from_xyz(filename): Return the zero-based index separating the two reactants in filename.

pyar.scripts.react.main(): Run the legacy reaction-search command-line workflow.

pyar.scripts.reaction_trace

Standalone reaction-trace analysis and plotting entrypoint.

pyar.scripts.reaction_trace.argument_parse(argv=None): Parse reaction-trace CLI arguments.

pyar.scripts.reaction_trace.main(argv=None): Run trace analysis and optionally emit plot artifacts.

pyar.scripts.similarity

Importable pyar-similarity entrypoint.

This utility computes Grigoryan-Springborg similarity across a pool of XYZ files, writes duplicate and unique structure collections, and records a summary file for the rejected pairs.

pyar.scripts.similarity.read_file(input_file)

pyar.scripts.similarity.Euclidean_distance(p1, p2, p3, axis_x, axis_y, axis_z)

pyar.scripts.similarity.average(data)

pyar.scripts.similarity.Grigoryan_Springborg(numb_atoms, array_coord_x_1, array_coord_y_1, array_coord_z_1, array_coord_x_2, array_coord_y_2, array_coord_z_2)

pyar.scripts.similarity.uniq(lst)

pyar.scripts.similarity.index_elements(duplicate_name, files_name)

pyar.scripts.similarity.process_files(x, array_keys, Info_Coords, threshold_duplicate, file_tmp, file_log, files_xyz)

pyar.scripts.similarity.main(): Scan XYZ files for near-duplicate structures and write summary files.

pyar.scripts.trial_generation

Command-line interface for trial geometry generation.

This utility exposes the orientation-sampling and fragment-merging helpers used by the aggregation and reaction workflows. It can generate approach directions, create candidate configurations, and export simple trial spheres.

pyar.scripts.trial_generation.main(): Generate trial placements or composite configurations.

Selection

pyar.selection

Selection services used by clustering and basin workflows.

pyar.selection.basin_memory

Persistence helpers for basin selection memory.

pyar.selection.basin_memory.record_selected_basins(selected_molecules, output_root='selected'): Persist final selected geometries in the per-stoichiometry basin registry.

pyar.selection.clustering

Clustering algorithms and cluster representatives for selection.

pyar.selection.clustering.determine_dbscan_params(dt)

pyar.selection.clustering.generate_labels(dt, algorithm='hdbscan', maximum_number_of_seeds=8)

pyar.selection.clustering.kmeans_clustering(dt, n_clusters)

pyar.selection.clustering.dbscan_clustering(dt)

pyar.selection.clustering.optics_clustering(dt)

pyar.selection.clustering.hdbscan_clustering(dt)

pyar.selection.clustering.affinity_propagation_clustering(dt)

pyar.selection.clustering.mean_shift_clustering(dt)

pyar.selection.clustering.spectral_clustering(dt, n_clusters)

pyar.selection.clustering.agglomerative_clustering(dt, n_clusters)

pyar.selection.clustering.gaussian_mixture_clustering(dt, n_components)

pyar.selection.clustering.rbf_kernel_clustering(dt, threshold=0.99)

pyar.selection.clustering.get_the_best_molecule(list_of_molecules)

pyar.selection.clustering.print_energy_table(molecules, stream=None, title=None): Report energies with relative values against the global minimum.

pyar.selection.clustering.select_best_from_each_cluster(labels, list_of_molecules)

pyar.selection.deduplication

Deduplication and connectivity filtering for selected geometries.

pyar.selection.deduplication.calc_fingerprint_distance(a, b): Calculate the distance between two fingerprints.

pyar.selection.deduplication.remove_similar(list_of_molecules): Remove near-duplicate geometries from a candidate pool.

pyar.selection.diversity

Diversity selection helpers.

pyar.selection.diversity.print_energy_table(molecules, stream=None, title=None): Report energies with relative values against the global minimum.

Similarity

pyar.similarity

pyar.similarity.read_file(input_file)

pyar.similarity.Euclidean_distance(p1, p2, p3, axis_x, axis_y, axis_z)

pyar.similarity.average(data)

pyar.similarity.Grigoryan_Springborg(numb_atoms, array_coord_x_1, array_coord_y_1, array_coord_z_1, array_coord_x_2, array_coord_y_2, array_coord_z_2)

pyar.similarity.uniq(lst)

pyar.similarity.index_elements(duplicate_name, files_name)

pyar.similarity.process_files(x, array_keys, Info_Coords, threshold_duplicate, file_tmp, file_log, files_xyz)

Solvation State

pyar.solvation_state

Compatibility wrapper for pyar.state.solvation.

Legacy code imported solvation restart-state classes from pyar.solvation_state. The real implementation now lives in pyar.state.solvation, and this module re-exports it so the old import path remains valid.

State

pyar.state

Restart-state entrypoints for the target package layout.

class pyar.state.AggregateRunState(root_directory, data)

Bases: object

Persist completed aggregation pathways independently of optimizer state.

classmethod create(root_directory, request, pathway_labels, legacy_import=None): Create and persist state for a new or imported aggregation run.

classmethod load(root_directory, expected_request): Load a running aggregation state file and validate its request.

validate_request(expected_request): Reject resume attempts that change the aggregation calculation.

validate_progress(): Reject incomplete or inconsistent persisted pathway progress.

completed_pathway_count(): Return the number of pathway builds already completed.

remaining_pathway_labels(): Return persisted pathways that still need to be calculated.

complete_pathway(label, selected_results): Persist completion and selected result paths for the next pathway.

finish(final_selected_results): Persist terminal workflow state and final selected output paths.

save(): Atomically write aggregates/state.json.

exception pyar.state.AggregateStateError

Bases: RuntimeError

Raised when an aggregation run cannot be safely resumed.

class pyar.state.ReactionRunState(root_directory, data)

Bases: object

Persist reaction workflow progress independently of optimizer objects.

classmethod create(root_directory, request, orientations, reactants): Create and persist state for a fresh reaction calculation.

classmethod load(root_directory, expected_request): Load a current-format reaction state file and validate its request.

classmethod migrate_legacy(root_directory, checkpoint, request): Convert an unambiguous legacy jobs.pkl checkpoint to JSON state.

validate_request(expected_request): Fail clearly when a resume invocation changes scientific settings.

remaining_gamma_schedule(): Return the numeric gamma values still to be processed.

pending_molecules(): Load the geometries still pending in the current gamma cycle.

current_survivor_molecules(): Load successful current-cycle candidates retained before interruption.

saved_product_identities(): Return saved product identifiers for restart-time deduplication.

record_job(job_name, gamma, status, remaining_orientations, current_survivors): Record processed work plus pending and retained current-cycle candidates.

record_product(job_name, gamma, inchi, smiles, path, trace_summary=None): Record and immediately persist one newly discovered product.

complete_cycle(gamma, next_orientations): Mark a gamma cycle complete and snapshot candidates for the next cycle.

finish(status='completed'): Persist terminal workflow state while retaining the run record.

save(): Atomically write reaction/state.json.

exception pyar.state.ReactionStateError

Bases: RuntimeError

Raised when a reaction run cannot be created or safely resumed.

class pyar.state.SolvationRunState(root_directory, data)

Bases: object

Persist completed solvation cycles independently of optimizer objects.

The state tracks the requested solvation calculation, the current seed geometries, the completed cycle history, and the terminal output paths. It is designed to be human-inspectable and safe to validate before a resumed run mutates the working directory.

classmethod create(root_directory, request, current_seeds)

Create and persist state for a new solvation run.

The initial state stores the request payload, snapshots of the input seed geometries, and the cycle counter used to drive the growth loop.

classmethod load(root_directory, expected_request)

Load a running solvation state file and validate its request.

A matching request is required for restart. If the state file belongs to a different calculation, the load is rejected rather than silently mutating an unrelated run directory.

validate_request(expected_request): Reject resume attempts that change the solvation calculation.

validate_progress(): Reject incomplete or inconsistent persisted cycle progress.

current_seed_molecules(): Load seed geometries to be used for the next solvation cycle.

complete_cycle(cycle_number, selected_molecules)

Persist a completed cycle and update seeds for the next cycle.

The selected molecules are snapshotted to disk so the next cycle can be resumed from an inspectable geometry set rather than from in-memory optimizer objects.

finish(final_status='completed'): Persist terminal workflow state and final selected output paths.

save(): Atomically write solvation/state.json.

exception pyar.state.SolvationStateError

Bases: RuntimeError

Raised when a solvation run cannot be safely resumed.

pyar.state.aggregate

Versioned, inspectable restart state for aggregation workflows.

exception pyar.state.aggregate.AggregateStateError

Bases: RuntimeError

Raised when an aggregation run cannot be safely resumed.

class pyar.state.aggregate.AggregateRunState(root_directory, data)

Bases: object

Persist completed aggregation pathways independently of optimizer state.

classmethod create(root_directory, request, pathway_labels, legacy_import=None): Create and persist state for a new or imported aggregation run.

classmethod load(root_directory, expected_request): Load a running aggregation state file and validate its request.

validate_request(expected_request): Reject resume attempts that change the aggregation calculation.

validate_progress(): Reject incomplete or inconsistent persisted pathway progress.

completed_pathway_count(): Return the number of pathway builds already completed.

remaining_pathway_labels(): Return persisted pathways that still need to be calculated.

complete_pathway(label, selected_results): Persist completion and selected result paths for the next pathway.

finish(final_selected_results): Persist terminal workflow state and final selected output paths.

save(): Atomically write aggregates/state.json.

pyar.state.reaction

Versioned, inspectable restart state for reaction workflows.

exception pyar.state.reaction.ReactionStateError

Bases: RuntimeError

Raised when a reaction run cannot be created or safely resumed.

class pyar.state.reaction.ReactionRunState(root_directory, data)

Bases: object

Persist reaction workflow progress independently of optimizer objects.

classmethod create(root_directory, request, orientations, reactants): Create and persist state for a fresh reaction calculation.

classmethod load(root_directory, expected_request): Load a current-format reaction state file and validate its request.

classmethod migrate_legacy(root_directory, checkpoint, request): Convert an unambiguous legacy jobs.pkl checkpoint to JSON state.

validate_request(expected_request): Fail clearly when a resume invocation changes scientific settings.

remaining_gamma_schedule(): Return the numeric gamma values still to be processed.

pending_molecules(): Load the geometries still pending in the current gamma cycle.

current_survivor_molecules(): Load successful current-cycle candidates retained before interruption.

saved_product_identities(): Return saved product identifiers for restart-time deduplication.

record_job(job_name, gamma, status, remaining_orientations, current_survivors): Record processed work plus pending and retained current-cycle candidates.

record_product(job_name, gamma, inchi, smiles, path, trace_summary=None): Record and immediately persist one newly discovered product.

complete_cycle(gamma, next_orientations): Mark a gamma cycle complete and snapshot candidates for the next cycle.

finish(status='completed'): Persist terminal workflow state while retaining the run record.

save(): Atomically write reaction/state.json.

pyar.state.reaction.read_legacy_checkpoint(root_directory): Read a legacy jobs.pkl only for one-time migration to JSON state.

pyar.state.solvation

Versioned, inspectable restart state for solvation workflows.

The solvation workflow persists a compact JSON state file plus geometry snapshots so interrupted runs can resume without redoing completed cycles or losing the selected seed geometries.

exception pyar.state.solvation.SolvationStateError

Bases: RuntimeError

Raised when a solvation run cannot be safely resumed.

class pyar.state.solvation.SolvationRunState(root_directory, data)

Bases: object

Persist completed solvation cycles independently of optimizer objects.

The state tracks the requested solvation calculation, the current seed geometries, the completed cycle history, and the terminal output paths. It is designed to be human-inspectable and safe to validate before a resumed run mutates the working directory.

classmethod create(root_directory, request, current_seeds)

Create and persist state for a new solvation run.

The initial state stores the request payload, snapshots of the input seed geometries, and the cycle counter used to drive the growth loop.

classmethod load(root_directory, expected_request)

Load a running solvation state file and validate its request.

A matching request is required for restart. If the state file belongs to a different calculation, the load is rejected rather than silently mutating an unrelated run directory.

validate_request(expected_request): Reject resume attempts that change the solvation calculation.

validate_progress(): Reject incomplete or inconsistent persisted cycle progress.

current_seed_molecules(): Load seed geometries to be used for the next solvation cycle.

complete_cycle(cycle_number, selected_molecules)

Persist a completed cycle and update seeds for the next cycle.

The selected molecules are snapshotted to disk so the next cycle can be resumed from an inspectable geometry set rather than from in-memory optimizer objects.

finish(final_status='completed'): Persist terminal workflow state and final selected output paths.

save(): Atomically write solvation/state.json.

Trial Generation

pyar.trial_generation

Compatibility shim for the legacy pyar.trial_generation module.

Workflow Results

pyar.workflow_results

Structured result objects returned by public workflow entrypoints.

class pyar.workflow_results.WorkflowResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: object

Common metadata for workflow outcomes.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

workflow: str

status: str

run_directory: str

state_path: str | None = None

selected_paths: tuple[str, ...] = ()

metadata: Mapping[str, Any]

to_dict(): Return a plain dictionary for logging or serialization.

class pyar.workflow_results.AggregateResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for aggregation runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

class pyar.workflow_results.SolvationResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for solvation runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

class pyar.workflow_results.ReactionResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for reaction runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

Workflows

pyar.workflows

Public workflow entrypoints for PyAR.

pyar.workflows.aggregate(molecules, aggregate_sizes, hm_orientations, qc_params, maximum_number_of_seeds, first_pathway, number_of_pathways, site)

Run an aggregate or cluster-generation workflow.

The function creates or resumes the aggregation state, iterates over the selected pathways, runs the per-orientation optimization for each path, and returns an AggregateResult describing the final run state.

pyar.workflows.react(reactant_a, reactant_b, gamma_min, gamma_max, hm_orientations, qc_params, site, proximity_factor)

Run the reaction-search workflow for two reactants.

The workflow iterates over the gamma schedule, optimizes each orientation, records products and trace summaries, and returns a structured result that summarizes the final reaction state.

pyar.workflows.solvate(seeds, monomer, aggregate_size, hm_orientations, qc_params, maximum_number_of_seeds, site=None)

Run the solvation workflow for the provided seeds and solvent.

The workflow either resumes an existing solvation/ state tree or creates a new one, then iterates over the requested growth cycles while recording the seed geometries selected for the next cycle. The returned SolvationResult describes the final run state and the output directory.

class pyar.workflows.WorkflowResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: object

Common metadata for workflow outcomes.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

workflow: str

status: str

run_directory: str

state_path: str | None = None

selected_paths: tuple[str, ...] = ()

metadata: Mapping[str, Any]

to_dict(): Return a plain dictionary for logging or serialization.

class pyar.workflows.AggregateResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for aggregation runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

class pyar.workflows.SolvationResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for solvation runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

class pyar.workflows.ReactionResult(workflow, status, run_directory, state_path=None, selected_paths=(), metadata=<factory>)

Bases: WorkflowResult

Structured result for reaction runs.

Parameters:

workflow (str)
status (str)
run_directory (str)
state_path (str | None)
selected_paths (tuple[str, ...])
metadata (Mapping[str, Any])

pyar.workflows._growth

Shared growth-workflow helpers for aggregate and solvation paths.

pyar.workflows._growth.random_permutation(iterable, r=None): Random selection from itertools.permutations(iterable, r).

pyar.workflows._growth.read_old_path(): Read restart pathway markers from a prior log, if one exists.

pyar.workflows._growth.old_path_to_new_path(monomers_to_be_added, old_path)

pyar.workflows._growth.select_pathways(monomers_to_be_added, number_of_pathways)

pyar.workflows._growth.read_orientations(molecule_id, noo)

pyar.workflows._growth.add_one(aggregate_id, seeds, monomer, hm_orientations, qc_params, maximum_number_of_seeds, site)

pyar.workflows._growth.check_for_the_finished_jobs_on_restart(list_of_optimized_molecules, cwd)

pyar.workflows._growth.generate_orientations(num_orientations, mol_id, monomer, seed_counter, seeds, site)

pyar.workflows._growth.update_id(aid, the_monomer): Increment one monomer count inside an aggregate identifier.

pyar.workflows._growth.check_stop_signal()

pyar.workflows._growth.expand_formula_to_aggregate_inputs(formula): Convert a formula into aggregate input symbols and multiplicities.

pyar.workflows._growth.generate_molecule_from_formula(formula, box_size=None, rng=None): Generate a molecule object from a chemical formula.

pyar.workflows.aggregate

Aggregate workflow orchestration for PyAR.

This module owns the aggregation and cluster-generation workflow used by pyar-cli -a and the legacy aggregator compatibility layer. It is responsible for:

validating the aggregate request and restart state
selecting pathways and orientation sets
creating the working directory tree under aggregates/
running the backend optimization steps for each pathway
collecting the selected geometries and workflow result metadata

The public entry points are aggregate() and aggregate_from_formulas().

pyar.workflows.aggregate.aggregate(molecules, aggregate_sizes, hm_orientations, qc_params, maximum_number_of_seeds, first_pathway, number_of_pathways, site)

Run an aggregate or cluster-generation workflow.

The function creates or resumes the aggregation state, iterates over the selected pathways, runs the per-orientation optimization for each path, and returns an AggregateResult describing the final run state.

pyar.workflows.aggregate.aggregate_from_formulas(formulas, aggregate_sizes, hm_orientations, qc_params, maximum_number_of_seeds, first_pathway, number_of_pathways, site)

Generate initial molecules from formulas and run the aggregate workflow.

This is the convenience entry point used by --formula aggregation runs. It converts the provided formulas into molecule objects and then delegates to aggregate().

pyar.workflows.aggregate.expand_formula_to_aggregate_inputs(formula): Convert a formula into aggregate input symbols and multiplicities.

pyar.workflows.aggregate.generate_molecule_from_formula(formula, box_size=None, rng=None): Generate a molecule object from a chemical formula.

pyar.workflows.reaction

Reaction workflow orchestration for PyAR.

This module owns the AFIR reaction-search pipeline:

build the numeric gamma schedule
prepare and persist restartable reaction state
generate trial orientations for each gamma cycle
optimize each orientation with the selected backend
perform unbiased relaxation when a bonded candidate is found
deduplicate and persist unique products
emit trace-analysis summaries for successful paths

The module is the implementation behind the legacy pyar.reactor import path and the pyar-react command-line entry point.

pyar.workflows.reaction.print_header(gamma_max, gamma_min, hm_orientations, software)

Log the fixed header used at the start of a reaction run.

The header mirrors the historical reactor logging style and gives the caller a single place to confirm the gamma range, orientation count, and backend before the workflow begins mutating the working directory.

pyar.workflows.reaction.with_gamma(qc_params, gamma)

Return a copy of qc_params with a specific AFIR gamma applied.

The helper also enables trace recording only for geomeTRIC-backed runs with a non-zero gamma, because those are the only configurations that produce the path trace used by the analysis tooling.

pyar.workflows.reaction.without_afir_bias(qc_params)

Return parameters for unbiased physical relaxation.

This is the relaxation step applied after a bonded AFIR candidate has been identified. It preserves the physical backend configuration while forcing gamma=0.0 so the candidate can be re-optimized without the AFIR bias.

pyar.workflows.reaction.build_gamma_schedule(gamma_min, gamma_max, steps=10)

Build the numeric AFIR gamma schedule used by the reaction workflow.

The schedule is inclusive and monotonic. A single-valued schedule is returned when the limits are equal; otherwise the workflow uses evenly spaced values between the endpoints.

pyar.workflows.reaction.format_gamma_id(gamma)

Format a gamma value for directory names and readable job labels.

The formatter keeps directory names stable and lexicographically useful by zero-padding the integral part and encoding the decimal separator as p.

pyar.workflows.reaction.build_reaction_request(reactant_a, reactant_b, gamma_list, hm_orientations, qc_params, site, proximity_factor)

Build the scientific request persisted with reaction restart state.

The request captures the scientifically relevant inputs that must remain fixed across restarts: the gamma schedule, the backend configuration, the selected site constraint, the proximity factor, and a signature of both reactants.

pyar.workflows.reaction.relax_without_afir_bias(molecule, qc_params)

Relax a bonded AFIR candidate on the unbiased physical objective.

The molecule is written to temporary XYZ snapshots before and after the relaxation so callers can inspect the pre- and post-relaxation geometries if the optimization succeeds.

pyar.workflows.reaction.initialize_reaction_run(reactant_a, reactant_b, gamma_min, gamma_max, hm_orientations, qc_params, site, proximity_factor)

Prepare a reaction run and return the mutable workflow state.

This function owns the restart contract for the reaction workflow. It either resumes an existing reaction state, migrates a legacy checkpoint, or creates a new reaction/ tree with all trial geometries staged for the first gamma cycle.

pyar.workflows.reaction.react(reactant_a, reactant_b, gamma_min, gamma_max, hm_orientations, qc_params, site, proximity_factor)

Run the reaction-search workflow for two reactants.

The workflow iterates over the gamma schedule, optimizes each orientation, records products and trace summaries, and returns a structured result that summarizes the final reaction state.

pyar.workflows.reaction.optimize_all(gamma_id, orientations, run_state, product_dir, qc_param)

Optimize all trial geometries for one gamma cycle.

Each orientation is written to its own job directory, optimized with the current gamma, and then either retained for the next gamma value or promoted to a unique product if it survives the unbiased relaxation step.

pyar.workflows.reaction.main(): Compatibility entry point retained for older imports and scripts.

pyar.workflows.solvation

Solvation workflow orchestration for PyAR.

This module owns the growth workflow behind pyar-cli --solvate. It persists a restartable solvation state, generates trial orientations for each cycle, and returns a structured result that describes the final selected seed geometries.

pyar.workflows.solvation.solvate(seeds, monomer, aggregate_size, hm_orientations, qc_params, maximum_number_of_seeds, site=None)

Run the solvation workflow for the provided seeds and solvent.

The workflow either resumes an existing solvation/ state tree or creates a new one, then iterates over the requested growth cycles while recording the seed geometries selected for the next cycle. The returned SolvationResult describes the final run state and the output directory.