PackLab 0.8.0__cp314-cp314-win_amd64.whl

PackLab/__init__.py

@@ -0,0 +1,13 @@
+from PackLab.units import ureg # noqa: F401
+from PackLab import samplers, monte_carlo, analytical  # noqa: F401
+
+debug_mode = False  # noqa: F401
+
+
+try:
+    from ._version import version as __version__  # noqa: F401
+
+except ImportError:
+    __version__ = "0.0.0"
+
+# -

PackLab/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)
+
+__commit_id__ = commit_id = None

PackLab/analytical/__init__.py

@@ -0,0 +1,3 @@
+from PackLab.analytical.domain import PercusYevickDomain  # noqa: F401
+from PackLab.analytical.solver import PercusYevickResult, PercusYevickSolver  # noqa: F401
+from PackLab.analytical.grid import make_wavenumber_grid  # noqa: F401

PackLab/analytical/domain.pyi

@@ -0,0 +1,19 @@
+from typing import Any
+
+class PercusYevickDomain:
+    def __init__(
+        self,
+        size: Any,
+        radii: Any,
+        volume_fraction: float,
+        number_fractions: Any,
+        rounding_mode: Any = ...,
+    ) -> None: ...
+    size: Any
+    radii: Any
+    volume_fraction: float
+    number_fractions: Any
+    particle_densities_per_radius: Any
+    def sample_radii(self, number_of_samples: int, seed: int | None = None) -> Any: ...
+    def print_bins(self, precision: int = 6) -> None: ...
+    def bins_table(self, precision: int = 6) -> str: ...

PackLab/analytical/grid.py

@@ -0,0 +1,55 @@
+"""Utilities for constructing reciprocal-space grids."""
+
+from typing import Any
+
+import numpy as np
+
+from PackLab.units import ureg
+
+
+def make_wavenumber_grid(
+    radial_resolution: Any,
+    maximum_distance: Any,
+    samples_per_oscillation: int = 12,
+) -> Any:
+    """Create a reciprocal-space grid for the radial inverse transform.
+
+    Parameters
+    ----------
+    radial_resolution : pint.Quantity
+        Smallest real-space feature to resolve. It determines the maximum
+        wavenumber through ``pi / radial_resolution``.
+    maximum_distance : pint.Quantity
+        Largest real-space distance at which the correlation function will be
+        evaluated. It determines the wavenumber spacing.
+    samples_per_oscillation : int, default=12
+        Samples used for one period of the sinc kernel at ``maximum_distance``.
+        Values below 8 are not recommended.
+
+    Returns
+    -------
+    pint.Quantity
+        A uniformly spaced, zero-inclusive wavenumber grid with units of
+        inverse length.
+    """
+    if samples_per_oscillation < 2:
+        raise ValueError("samples_per_oscillation must be at least 2.")
+
+    resolution_m = radial_resolution.to("meter")
+    maximum_distance_m = maximum_distance.to("meter")
+    if resolution_m.magnitude <= 0:
+        raise ValueError("radial_resolution must be positive.")
+    if maximum_distance_m.magnitude <= 0:
+        raise ValueError("maximum_distance must be positive.")
+
+    maximum_wavenumber = np.pi / resolution_m
+    wavenumber_step = 2 * np.pi / (samples_per_oscillation * maximum_distance_m)
+    number_of_points = int(
+        np.ceil((maximum_wavenumber / wavenumber_step).to_base_units().magnitude)
+    ) + 1
+
+    return np.linspace(
+        0.0,
+        maximum_wavenumber.to("1 / meter").magnitude,
+        number_of_points,
+    ) / ureg.meter

PackLab/analytical/solver.pyi

@@ -0,0 +1,21 @@
+from typing import Any, Literal
+
+class PercusYevickResult:
+    radii: Any
+    densities: Any
+    wavenumber: Any
+    distances: Any
+    g: Any
+    h: Any
+    H: Any
+
+class PercusYevickSolver:
+    def __init__(
+        self,
+        densities: Any,
+        radii: Any,
+        wavenumber: Any | Literal["auto"] = "auto",
+        radial_resolution: Any | None = None,
+        samples_per_oscillation: int = 12,
+    ) -> None: ...
+    def compute(self, distances: Any) -> PercusYevickResult: ...

PackLab/directories.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; py-indent-offset:4 -*-
+
+from pathlib import Path
+import PackLab
+
+root_path = Path(PackLab.__path__[0])
+
+repository = project_path = Path(root_path)
+
+doc_css_path = project_path.parent / "docs/source/_static/default.css"
+
+data = repository / "data"
+

PackLab/monte_carlo/__init__.py

@@ -0,0 +1,14 @@
+from PackLab.monte_carlo import result as _result  # noqa: F401
+from PackLab.monte_carlo.domain import PackingDomain  # noqa: F401
+from PackLab.monte_carlo.simulator import RSAOptions, RSASimulator, PackingConfiguration  # noqa: F401
+from PackLab.monte_carlo.metropolis import (
+    MetropolisOptions as MetropolisOptions,
+    MetropolisSimulator as MetropolisSimulator,
+    MetropolisStatistics as MetropolisStatistics,
+)
+from PackLab.monte_carlo.statistics import PackingStatistics  # noqa: F401
+from PackLab.monte_carlo.estimator import PackingEstimator, PackingEstimate  # noqa: F401
+from PackLab.monte_carlo.results import PackingResult  # noqa: F401
+from PackLab.monte_carlo.persistence import LoadedPackingConfiguration, load_packing, save_packing  # noqa: F401
+from PackLab.monte_carlo.diagnostics import MetropolisDiagnosticReport, run_metropolis_diagnostics  # noqa: F401
+from PackLab.monte_carlo.structure import EmpiricalStructure, empirical_structure  # noqa: F401

PackLab/monte_carlo/diagnostics.py

@@ -0,0 +1,198 @@
+"""Low-memory diagnostics for fixed-volume Metropolis hard-sphere sampling."""
+
+
+from dataclasses import dataclass
+from statistics import NormalDist
+from typing import Any, Callable
+
+import numpy as np
+
+from PackLab.units import ureg
+
+
+@dataclass(frozen=True, slots=True)
+class MetropolisDiagnosticReport:
+    """
+    Retained diagnostics from a sampled Metropolis trajectory.
+
+    Notes
+    -----
+    These summaries quantify the recorded observable only. They do not prove
+    or automatically assert equilibration.
+    """
+
+    sample_sweeps: np.ndarray
+    acceptance_rates: np.ndarray
+    accepted_move_deltas: np.ndarray
+    rejected_move_deltas: np.ndarray
+    mean_squared_displacements: Any
+    observable: np.ndarray
+    observable_name: str
+    burn_in_sweeps: int
+    autocorrelation_time: float
+    effective_sample_size: float
+    block_means: np.ndarray
+    standard_error: float
+    confidence_interval: tuple[float, float]
+    confidence_level: float
+    final_result: Any
+
+
+def _validate_integer(name: str, value: int, minimum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, (int, np.integer)) or value < minimum:
+        raise ValueError(f"{name} must be an integer greater than or equal to {minimum}.")
+    return int(value)
+
+
+def _autocorrelation_time(values: np.ndarray) -> float:
+    centered = values - values.mean()
+    variance = np.dot(centered, centered) / values.size
+    if variance == 0.0:
+        return 0.5
+    correlations = np.correlate(centered, centered, mode="full")[values.size - 1 :] / (
+        variance * np.arange(values.size, 0, -1)
+    )
+    tau = 0.5
+    for correlation in correlations[1:]:
+        if correlation <= 0.0:
+            break
+        tau += float(correlation)
+    return tau
+
+
+def run_metropolis_diagnostics(
+    simulator: Any,
+    number_of_sweeps: int,
+    *,
+    sample_interval: int = 10,
+    burn_in_sweeps: int = 0,
+    observable: Callable[[Any], float] | None = None,
+    observable_name: str = "mean_squared_displacement_m2",
+    block_size: int | None = None,
+    confidence_level: float = 0.95,
+) -> MetropolisDiagnosticReport:
+    """
+    Run sampled chunks of a Metropolis simulation without retaining positions.
+
+    Parameters
+    ----------
+    simulator : MetropolisSimulator
+        Native public simulator to advance. It is not reset by this function.
+    number_of_sweeps : int
+        Number of additional sweeps to execute.
+    sample_interval : int, default=10
+        Number of sweeps between retained observations.
+    burn_in_sweeps : int, default=0
+        Initial sweeps excluded from autocorrelation and block statistics.
+    observable : callable, optional
+        Function taking the current ``PackingConfiguration`` and returning one
+        finite scalar. The default records mean squared displacement (MSD).
+    observable_name : str, default="mean_squared_displacement_m2"
+        Label for the scalar observable in the report.
+    block_size : int, optional
+        Number of post-burn-in samples per block. By default it is selected
+        from the estimated autocorrelation time.
+    confidence_level : float, default=0.95
+        Open-interval normal confidence level for the block-mean estimate.
+
+    Returns
+    -------
+    MetropolisDiagnosticReport
+        Move deltas, per-sample rates, MSD relative to the starting state, and
+        autocorrelation/block summaries. MSD uses accumulated accepted moves,
+        including periodic crossings, relative to the start of this call.
+        The report does not establish equilibration.
+    """
+    total = _validate_integer("number_of_sweeps", number_of_sweeps, 1)
+    interval = _validate_integer("sample_interval", sample_interval, 1)
+    burn_in = _validate_integer("burn_in_sweeps", burn_in_sweeps, 0)
+    if burn_in >= total:
+        raise ValueError("burn_in_sweeps must be smaller than number_of_sweeps.")
+    if not 0.0 < confidence_level < 1.0:
+        raise ValueError("confidence_level must lie strictly between 0 and 1.")
+    if not callable(getattr(simulator, "run_sweeps", None)):
+        raise TypeError("simulator must be a MetropolisSimulator exposing run_sweeps().")
+
+    start_displacement = np.asarray(
+        simulator.cumulative_displacements.to("meter").magnitude, dtype=float
+    ).copy()
+    previous_accepted = int(simulator.statistics.accepted_moves)
+    previous_rejected = int(simulator.statistics.rejected_moves)
+    sweeps: list[int] = []
+    rates: list[float] = []
+    accepted: list[int] = []
+    rejected: list[int] = []
+    msd: list[float] = []
+    observations: list[float] = []
+    completed = 0
+    final_result = None
+    while completed < total:
+        chunk = min(interval, total - completed)
+        final_result = simulator.run_sweeps(chunk)
+        completed += chunk
+        current_statistics = simulator.statistics
+        accepted_delta = current_statistics.accepted_moves - previous_accepted
+        rejected_delta = current_statistics.rejected_moves - previous_rejected
+        attempted_delta = accepted_delta + rejected_delta
+        displacement = np.asarray(
+            simulator.cumulative_displacements.to("meter").magnitude, dtype=float
+        ) - start_displacement
+        current_msd = float(
+            np.mean(np.einsum("ij,ij->i", displacement, displacement))
+        )
+        value = (
+            current_msd if observable is None else float(observable(simulator.sphere_configuration))
+        )
+        if not np.isfinite(value):
+            raise ValueError("observable must return a finite scalar.")
+        sweeps.append(completed)
+        rates.append(accepted_delta / attempted_delta if attempted_delta else 0.0)
+        accepted.append(accepted_delta)
+        rejected.append(rejected_delta)
+        msd.append(current_msd)
+        observations.append(value)
+        previous_accepted = int(current_statistics.accepted_moves)
+        previous_rejected = int(current_statistics.rejected_moves)
+
+    sample_sweeps = np.asarray(sweeps, dtype=int)
+    selected = sample_sweeps > burn_in
+    post_burn_values = np.asarray(observations, dtype=float)[selected]
+    if post_burn_values.size < 2:
+        raise ValueError("burn-in leaves fewer than two retained samples for diagnostics.")
+    tau = _autocorrelation_time(post_burn_values)
+    ess = post_burn_values.size / (2.0 * tau)
+    selected_block_size = (
+        int(np.ceil(2.0 * tau))
+        if block_size is None
+        else _validate_integer("block_size", block_size, 1)
+    )
+    blocks = [
+        post_burn_values[index : index + selected_block_size].mean()
+        for index in range(0, post_burn_values.size, selected_block_size)
+        if post_burn_values[index : index + selected_block_size].size == selected_block_size
+    ]
+    if len(blocks) < 2:
+        raise ValueError(
+            "fewer than two complete blocks remain; reduce block_size or collect more samples."
+        )
+    block_means = np.asarray(blocks)
+    standard_error = float(block_means.std(ddof=1) / np.sqrt(block_means.size))
+    z_value = NormalDist().inv_cdf((1.0 + confidence_level) / 2.0)
+    mean = float(block_means.mean())
+    return MetropolisDiagnosticReport(
+        sample_sweeps=sample_sweeps,
+        acceptance_rates=np.asarray(rates),
+        accepted_move_deltas=np.asarray(accepted, dtype=int),
+        rejected_move_deltas=np.asarray(rejected, dtype=int),
+        mean_squared_displacements=np.asarray(msd) * ureg.meter**2,
+        observable=np.asarray(observations),
+        observable_name=observable_name,
+        burn_in_sweeps=burn_in,
+        autocorrelation_time=tau,
+        effective_sample_size=ess,
+        block_means=block_means,
+        standard_error=standard_error,
+        confidence_interval=(mean - z_value * standard_error, mean + z_value * standard_error),
+        confidence_level=confidence_level,
+        final_result=final_result,
+    )

PackLab/monte_carlo/diagnostics.pyi

@@ -0,0 +1,30 @@
+from typing import Any, Callable
+
+class MetropolisDiagnosticReport:
+    sample_sweeps: Any
+    acceptance_rates: Any
+    accepted_move_deltas: Any
+    rejected_move_deltas: Any
+    mean_squared_displacements: Any
+    observable: Any
+    observable_name: str
+    burn_in_sweeps: int
+    autocorrelation_time: float
+    effective_sample_size: float
+    block_means: Any
+    standard_error: float
+    confidence_interval: tuple[float, float]
+    confidence_level: float
+    final_result: Any
+
+def run_metropolis_diagnostics(
+    simulator: Any,
+    number_of_sweeps: int,
+    *,
+    sample_interval: int = ...,
+    burn_in_sweeps: int = ...,
+    observable: Callable[[Any], float] | None = ...,
+    observable_name: str = ...,
+    block_size: int | None = ...,
+    confidence_level: float = ...,
+) -> MetropolisDiagnosticReport: ...

PackLab/monte_carlo/domain.pyi

@@ -0,0 +1,15 @@
+from typing import Any
+
+class PackingDomain:
+    def __init__(
+        self, length_x: Any, length_y: Any, length_z: Any, use_periodic_boundaries: bool
+    ) -> None: ...
+    @property
+    def length_x(self) -> Any: ...
+    @property
+    def length_y(self) -> Any: ...
+    @property
+    def length_z(self) -> Any: ...
+    volume: float
+    use_periodic_boundaries: bool
+    def scale(self, scale_factor: float) -> None: ...

PackLab/monte_carlo/estimator.pyi

@@ -0,0 +1,27 @@
+from typing import Any
+from PackLab.monte_carlo.domain import PackingDomain
+from PackLab.monte_carlo.simulator import RSAOptions
+from PackLab.samplers import RadiusSampler
+
+class PackingEstimate:
+    centers: Any
+    mean_g: Any
+    std_g: Any
+    number_of_species: int
+    number_of_bins: int
+
+class PackingEstimator:
+    def __init__(
+        self,
+        domain: PackingDomain,
+        radius_sampler: RadiusSampler,
+        options: RSAOptions,
+        number_of_bins: int,
+    ) -> None: ...
+    def estimate(
+        self,
+        number_of_samples: int,
+        maximum_pairs: int = 0,
+        progress: bool = False,
+        progress_interval: int = 1,
+    ) -> PackingEstimate: ...

PackLab/monte_carlo/metropolis.pyi

@@ -0,0 +1,36 @@
+from typing import Any
+
+from PackLab.monte_carlo.domain import PackingDomain
+from PackLab.monte_carlo.simulator import PackingConfiguration
+
+
+class MetropolisOptions:
+    random_seed: int
+    number_of_sweeps: int
+    maximum_displacement: Any
+
+
+class MetropolisStatistics:
+    attempted_moves: int
+    accepted_moves: int
+    rejected_moves: int
+    completed_sweeps: int
+    total_runtime_seconds: float
+    acceptance_rate: float
+
+
+class MetropolisSimulator:
+    def __init__(
+        self,
+        domain: PackingDomain,
+        initial_configuration: PackingConfiguration,
+        options: MetropolisOptions,
+    ) -> None: ...
+    sphere_configuration: PackingConfiguration
+    domain: PackingDomain
+    statistics: MetropolisStatistics
+    @property
+    def cumulative_displacements(self) -> Any: ...
+    def reset(self) -> None: ...
+    def run(self) -> Any: ...
+    def run_sweeps(self, number_of_sweeps: int) -> Any: ...