DebyeCalculator¶

class debyecalculator.debye_calculator.DebyeCalculator(qmin: float = 1.0, qmax: float = 30.0, qstep: float = 0.05, qdamp: float = 0.04, rmin: float = 0.0, rmax: float = 20.0, rstep: float = 0.01, rthres: float = 0.0, biso: float = 0.3, device: str = 'cuda', batch_size: Optional[int] = 10000, lorch_mod: bool = False, radiation_type: str = 'xray', profile: bool = False, _max_batch_size: int = 4000, _lightweight_mode: bool = False)¶

Calculate the scattering intensity I(Q) through the Debye scattering equation, the Total Scattering Structure Function S(Q), the Reduced Total Scattering Function F(Q), and the Reduced Atomic Pair Distribution Function G(r) for a given atomic structure.

fq(structure_source: Union[Tuple[List[str], Union[ndarray, Tensor]], Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]], List[Tuple[List[str], Union[ndarray, Tensor]]], List[Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]]], str, List[str], Atoms, List[Atoms]], radii: Optional[Union[List[float], float]] = None, keep_on_device: bool = False) → Union[FqTuple, List[FqTuple]]¶

Calculate the structure function S(Q) for the given atomic structure(s).

Parameters:

structure_source (StructureSourceType) – Atomic structure source in XYZ/CIF format, ASE Atoms object, or as a tuple of (atomic_identities, atomic_positions).
radii (Union[List[float], float, None]) – List/float of radii/radius of particle(s) to generate with parsed CIF.
keep_on_device (bool) – Flag to keep the results on the class device. Default is False, and will return numpy arrays on CPU.

Returns:

SqTuple containing Q-values and structure function S(Q) or a list of such tuples.

Return type:

Union[SqTuple, List[SqTuple]]

Raises:

TypeError – If the structure source is of an invalid type.
IOError – If there is an issue loading the structure from the specified file.
ValueError – If the file extension is not valid or when providing .cif data file, radii is not provided.

gr(structure_source: Union[Tuple[List[str], Union[ndarray, Tensor]], Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]], List[Tuple[List[str], Union[ndarray, Tensor]]], List[Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]]], str, List[str], Atoms, List[Atoms]], radii: Optional[Union[List[float], float]] = None, keep_on_device: bool = False) → Union[GrTuple, List[GrTuple]]¶

Calculate the reduced pair distribution function G(r) for the given atomic structure(s).

Parameters:

structure_source (StructureSourceType) – Atomic structure source in XYZ/CIF format, ASE Atoms object, or as a tuple of (atomic_identities, atomic_positions).
radii (Union[List[float], float, None]) – List/float of radii/radius of particle(s) to generate with parsed CIF.
keep_on_device (bool) – Flag to keep the results on the class device. Default is False, and will return numpy arrays on CPU.

Returns:

GrTuple containing r-values and reduced pair distribution function G(r) or a list of such tuples.

Return type:

Union[GrTuple, List[GrTuple]]

Raises:

TypeError – If the structure source is of an invalid type.
IOError – If there is an issue loading the structure from the specified file.
ValueError – If the file extension is not valid or when providing .cif data file, radii is not provided.

interact(_cont_updates: bool = False) → None¶

Initiates an interactive visualization and data analysis tool within a Jupyter Notebook or Google Colab environment.

Parameters:: _cont_updates (bool, optional) – If True, enables continuous updates for interactive widgets. Defaults to False.

iq(structure_source: Union[Tuple[List[str], Union[ndarray, Tensor]], Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]], List[Tuple[List[str], Union[ndarray, Tensor]]], List[Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]]], str, List[str], Atoms, List[Atoms]], radii: Optional[Union[List[float], float]] = None, keep_on_device: bool = False, _self_scattering: bool = True) → Union[IqTuple, List[IqTuple]]¶

Calculate the scattering intensity I(Q) for the given atomic structure(s).

Parameters:

structure_source (StructureSourceType) – Atomic structure source in XYZ/CIF format, ASE Atoms object, or as a tuple of (atomic_identities, atomic_positions).
radii (Union[List[float], float, None]) – List/float of radii/radius of particle(s) to generate with parsed CIF.
keep_on_device (bool) – Flag to keep the results on the class device. Default is False, and will return numpy arrays on CPU.
_self_scattering (bool) – Flag to compute self-scattering contribution. Default is True.

Returns:

IqTuple containing Q-values and scattering intensity I(Q) or a list of such tuples.

Return type:

Union[IqTuple, List[IqTuple]]

Raises:

TypeError – If the structure source is of an invalid type.
IOError – If there is an issue loading the structure from the specified file.
ValueError – If the file extension is not valid or when providing .cif data file, radii is not provided.

parameter_constraint_assertion() → None¶

Assert that all parameters meet valid constraints.

Raises:: ValueError – If any of the parameters violate the specified constraints.

sq(structure_source: Union[Tuple[List[str], Union[ndarray, Tensor]], Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]], List[Tuple[List[str], Union[ndarray, Tensor]]], List[Tuple[Union[List[int], ndarray, Tensor], Union[ndarray, Tensor]]], str, List[str], Atoms, List[Atoms]], radii: Optional[Union[List[float], float]] = None, keep_on_device: bool = False) → Union[SqTuple, List[SqTuple]]¶

Calculate the structure function S(Q) for the given atomic structure(s)

Parameters:

structure_source (StructureSourceType) – Atomic structure source in XYZ/CIF format, ASE Atoms object or as a tuple of (atomic_identities, atomic_positions)
keep_on_device (bool) – Flag to keep the results on the class device. Default is False, and will return numpy arrays on CPU

Returns:

SqTuple containing Q-values and structure function S(Q)

update_parameters(**kwargs: Any) → None¶

Set or update the parameters of the DebyeCalculator.

Parameters:: **kwargs – Arbitrary keyword arguments to update the parameters.
Raises:: ValueError – If any of the updated parameters violate the specified constraints.

Utility Functions¶

debyecalculator.utility.generate.get_default_atoms(atom_type: str, output_type: str = 'number') → List[str]¶

Get the default atoms based on the atom type and output type.

Parameters: - atom_type (str): The type of atoms to retrieve. Accepts either “metal” or “ligand”. - output_type (str): The type of output to retrieve. Accepts either “number” or “symbol”. Defaults to “number”.

Returns: - atoms (list): The list of default atoms based on the atom type and output type.

Raises: - ValueError: If the atom_type is not “metal” or “ligand”. - ValueError: If the output_type is not “number” or “symbol”.

debyecalculator.utility.generate.generate_nanoparticles(cif_file: str, radii: Union[List[float], float], metals: Union[List[float], List[str], str] = 'Default', ligands: Union[List[float], List[str], str] = 'Default', sort_atoms: bool = True, disable_pbar: bool = False, return_graph_elements: bool = False, device: str = 'cuda', _override_device: bool = False, _lightweight_mode: bool = False, _return_ase: bool = False, _reverse_order: bool = True, _benchmarking: bool = False) → Union[List[NanoParticle], NanoParticle, List[NanoParticleASE], NanoParticleASE, List[NanoParticleASEGraph], NanoParticleASEGraph]¶

Generate spherical nanoparticles from a given CIF and radii.

Parameters:

cif_file (str) – Input CIF file.
radii (Union[List[float], float]) – List of floats or float of radii for nanoparticles to be generated.
metals (Union[List[float], List[str], str]) – List of metals, their symbols, or ‘Default’ for default metal atoms.
ligands (Union[List[float], List[str], str]) – List of ligands, their symbols, or ‘Default’ for default ligand atoms.
sort_atoms (bool, optional) – Whether to sort atoms in the nanoparticle. Defaults to True.
disable_pbar (bool, optional) – Whether to disable the progress bar. Defaults to False.
return_graph_elements (bool, optional) – Whether to return graph elements. Defaults to False.
device (str) – Device to use for computations (‘cuda’ for CUDA-enabled GPU’s or ‘cpu’ for CPU)
_override_device (bool) – Ignore object device and run on CPU.
_lightweight_mode (bool) – Whether to use lightweight mode. Defaults to False.
_return_ase (bool) – Whether to return ASE objects. Defaults to False.
_reverse_order (bool) – Whether to generate particles in reverse radii order
_benchmarking (bool) – Stripped down version for benchmarking

Returns:

List of nanoparticle tuples or ASE objects.

Return type:

NanoParticleType

Profiling Functions¶

class debyecalculator.utility.profiling.Profiler¶

This class provides a simple profiling mechanism for measuring the execution time of different sections of code. It records the time taken for each named section of code and calculates the mean and variance of the recorded times.

__init__()¶: Initialize the Profiler object with default settings.

reset()¶: Reset the profiler data and start tracking time from the current point.

time(name)¶: Record the execution time for a specific section of code with the given name.

means()¶: Get the dictionary of mean times for each recorded section.

vars()¶: Get the dictionary of variances of the recorded times for each section.

stds()¶: Get the dictionary of standard deviations of the recorded times for each section.

total()¶: Calculate the total time taken for all recorded sections.

summary(prefix='')¶: Generate a summary of the profiling data with mean time, standard deviation, and percentage of total time for each recorded section.

Usage::

The Profiler object can be used to measure the execution time of different parts of a code by calling the time method with a descriptive name for each section. After profiling, the summary method can be used to print a summary of the profiling data.

Example::

profiler = Profiler() for i in range(10):

# Code segment to be profiled profiler.time(“Code Segment %d” % i)

print(profiler.summary(“Profiling Results:”))

Benchmark Functions¶

class debyecalculator.utility.benchmark.DebyeBenchmarker(function: str = 'gr', radii: Union[List, ndarray, Tensor] = [5], show_progress_bar: bool = True, custom_cif: Optional[str] = None, **kwargs)¶

A class for benchmarking Debye calculations.

benchmark(generate_individually: bool = True, repetitions: int = 1, dummy_repititions: int = 2) → Statistics¶

Benchmark DebyeCalculator.

Parameters:

generate_individually (bool) – Flag to benchmark individually for each radius.
repetitions (int) – Number of repetitions for benchmarking.

Returns:

Benchmark statistics.

Return type:

Statistics

get_reference_stat_diffpy() → Statistics¶

Get the reference statistics for DiffPy-CMI

Returns:: DiffPy-CMI
Return type:: Statistics

get_reference_stat_titan() → Statistics¶

Get the reference statistics for TITAN RTX

Returns:: TITAN RTX
Return type:: Statistics

set_batch_size(batch_size: int) → None¶

Set the batch size for Debye calculations.

Parameters:: batch_size (int) – Batch size for calculations.

set_debye_parameters(**debye_parameters: Any) → None¶

Set Debye parameters for the calculator.

Parameters:: **debye_parameters – Keyword arguments for Debye parameters.

set_device(device: str) → None¶

Set the device for Debye calculations.

Parameters:: device (str) – Device to be set for calculations.

set_radii(radii: Union[List, ndarray, Tensor]) → None¶

Set the radii for benchmarking.

Parameters:: radii (Union[List, np.ndarray, torch.Tensor]) – List of radii for benchmarking.

class debyecalculator.utility.benchmark.Statistics(name: str, function_name: str, device: str, batch_size: int, radii: List[float], num_atoms: List[int], means: List[float], stds: List[float], cuda_mem_structure: List[float], cuda_mem_calculations: List[float])¶: A class to store and represent benchmark statistics.

debyecalculator.utility.benchmark.from_csv(path: str) → Statistics¶

Load Statistics instance from a CSV file.

Parameters:: path (str) – Path to the CSV file.
Returns:: Loaded Statistics instance.
Return type:: Statistics
Raises:: IOError – If the CSV file cannot be read.

debyecalculator.utility.benchmark.plot_memory_statistics(statistics: List[Statistics] = [], labels: Optional[List[str]] = None, figsize: tuple = (8, 8), include_references: bool = False, log_scale: bool = True, return_fig: bool = False) → Union[None, figure]¶

Plots memory statistics

Parameters:

statistics (List[Statistics]) – List of Statistics objects
labels (Union[List[str], None]) – List of labels for the plot. If None, labels are generated from statistics.
figsize (tuple) – Figure size, default is (8, 8).
include_references (bool) – Whether to include reference data, default is False.
log_scale (bool) – Whether to use a logarithmic scale for the y-axis, default is True.
return_fig (bool) – If True, returns the matplotlib figure instead of displaying it, default is False.

Returns:

If return_fig is True, returns the matplotlib figure. Otherwise, displays the plot.

Return type:

Union[None, plt.figure]

debyecalculator.utility.benchmark.plot_time_statistics(statistics: List[Statistics] = [], labels: Optional[List[str]] = None, figsize: tuple = (8, 6), include_references: bool = False, log_scale: bool = True, return_fig: bool = False) → Union[None, figure]¶

Plots time statistics

Parameters:

statistics (List[Statistics]) – List of Statistics objects
labels (Union[List[str], None]) – List of labels for the plot. If None, labels are generated from statistics.
figsize (tuple) – Figure size, default is (8, 6).
include_references (bool) – Whether to include reference data, default is False.
log_scale (bool) – Whether to use a logarithmic scale for the y-axis, default is True.
return_fig (bool) – If True, returns the matplotlib figure instead of displaying it, default is False.

Returns:

If return_fig is True, returns the matplotlib figure. Otherwise, displays the plot.

Return type:

Union[None, plt.figure]

debyecalculator.utility.benchmark.to_csv(stat: Statistics, path: str) → None¶

Save Statistics instance to a CSV file.

Parameters:

stat (Statistics) – Statistics instance to be saved.
path (str) – Path to save the CSV file.