httk-analyse 2.1.0__py3-none-any.whl

httk/analyse/__init__.py

@@ -0,0 +1,26 @@
+"""Analysis capabilities for the httk namespace package."""
+
+from httk.core import register_citation
+
+register_citation(
+    applies_to="Numerical analysis uses NumPy",
+    references={
+        "authors": (
+            {"name": "Charles R. Harris"},
+            {"name": "K. Jarrod Millman"},
+            {"name": "Stéfan J. van der Walt"},
+            {"name": "and others"},
+        ),
+        "title": "Array programming with NumPy",
+        "journal": "Nature",
+        "volume": "585",
+        "pages": "357-362",
+        "year": "2020",
+        "doi": "10.1038/s41586-020-2649-2",
+        "bib_type": "article",
+    },
+)
+
+from . import crysviz, generic, matsci
+
+__all__ = ["crysviz", "generic", "matsci"]

httk/analyse/crysviz.py

@@ -0,0 +1,105 @@
+"""Open httk structures in the CrysViz viewer."""
+
+import os
+import tempfile
+from pathlib import Path, PureWindowsPath
+from typing import Any
+
+from httk.core import register_citation, save
+
+
+def _import_crysviz() -> Any:
+    try:
+        import crysviz  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise ImportError("httk.analyse.crysviz requires crysviz; install httk-analyse[crysviz]") from exc
+    return crysviz
+
+
+def _safe_filename(name: str) -> bool:
+    """Return whether ``name`` is a non-path filename usable on every platform."""
+    return bool(
+        name
+        and name not in {".", ".."}
+        and not any(character in name for character in "/\\")
+        and not Path(name).is_absolute()
+        and not PureWindowsPath(name).is_absolute()
+        and not PureWindowsPath(name).drive
+        and all(character.isprintable() for character in name)
+    )
+
+
+def to_payload(
+    structure: Any,
+    *,
+    name: str | None = None,
+    format: str = "vasp-poscar",
+) -> Any:
+    """Serialize an httk structure as an in-memory CrysViz payload.
+
+    :param structure: Structure to serialize.
+    :param name: Optional filename for the payload, without a path.
+    :param format: Serialization format, either ``"vasp-poscar"`` or ``"cif"``.
+    :return: A CrysViz payload containing the serialized structure.
+    :raises ImportError: If CrysViz is not installed.
+    :raises ValueError: If ``format`` is not supported.
+    """
+    if format not in {"vasp-poscar", "cif"}:
+        raise ValueError("format must be 'vasp-poscar' or 'cif'")
+
+    crysviz = _import_crysviz()
+    suffix = ".vasp" if format == "vasp-poscar" else ".cif"
+    if name:
+        if not _safe_filename(name):
+            raise ValueError("name must be a nonempty filename without a path")
+        filename = name
+    else:
+        formula = getattr(structure, "formula", None)
+        formula_text = str(formula) if formula is not None else ""
+        filename = formula_text if _safe_filename(formula_text) else "structure"
+    if not filename.casefold().endswith(suffix):
+        filename += suffix
+
+    with tempfile.TemporaryDirectory() as directory:
+        destination = Path(directory) / f"structure{suffix}"
+        save(structure, destination, format=format)
+        text = destination.read_text(encoding="utf-8")
+    return crysviz.Payload(filename, text)
+
+
+def show(*structures: Any, **viewer_kwargs: Any) -> Any:
+    r"""Open structures in CrysViz and return when its window is ready.
+
+    :param \*structures: CrysViz payloads, source paths, or httk structures to display.
+    :param \**viewer_kwargs: Keyword arguments forwarded to ``crysviz.show``.
+    :return: The ready CrysViz viewer, which also supports the context-manager protocol.
+    :raises ImportError: If CrysViz is not installed.
+
+    The call is non-blocking after the window is ready. Call ``viewer.wait()`` to
+    block until the window closes.
+    """
+    crysviz = _import_crysviz()
+    sources: list[Any] = []
+    for structure in structures:
+        if isinstance(structure, (crysviz.Payload, str, os.PathLike)):
+            sources.append(structure)
+        else:
+            sources.append(to_payload(structure))
+
+    register_citation(
+        applies_to="Structure visualisation uses CrysViz",
+        references={
+            "authors": (
+                {"name": "Florian Trybel"},
+                {"name": "Abhijith S Parackal"},
+                {"name": "Oscar Bulancea-Lindvall"},
+                {"name": "Henricus R.A. ten Eikelder"},
+                {"name": "Rickard Armiento"},
+            ),
+            "title": "CrysViz - Crystal Structure Visualisation & Analysis",
+            "url": "https://github.com/CrysViz/crysviz",
+            "year": "2026",
+            "bib_type": "misc",
+        },
+    )
+    return crysviz.show(sources, **viewer_kwargs)

httk/analyse/generic/__init__.py

@@ -0,0 +1,5 @@
+"""Generic numerical analysis independent of a scientific domain."""
+
+from .lower_hull import LowerConvexHull
+
+__all__ = ["LowerConvexHull"]

httk/analyse/generic/_highs.py

@@ -0,0 +1,134 @@
+"""Optional HiGHS candidate-basis provider for lower-hull mixtures."""
+
+import importlib
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+
+from ._simplex import _PIVOT_TOLERANCE, _basis_is_well_conditioned, _scaled_independent_equalities, _simplex_iterations
+
+highspy: Any = importlib.import_module("highspy")
+
+
+class _HighsMixtureSolver:
+    """Reuse one HiGHS model while retaining the local simplex as final arbiter."""
+
+    def __init__(self, points: Sequence[Sequence[float]], values: Sequence[float]) -> None:
+        self._points = points
+        self._values = values
+        self._enabled = set(range(len(points)))
+        self._model: Any = None
+        try:
+            coordinates = np.asarray(points, dtype=np.float64)
+            origin = coordinates[0]
+            relative = coordinates - origin
+            scale = np.max(np.abs(relative), axis=0)
+            scale[scale == 0.0] = 1.0
+            matrix = np.vstack(((relative / scale).T, np.ones(len(points))))
+            costs = np.asarray(values, dtype=np.float64)
+            shifted_costs = costs - np.min(costs)
+            if not (np.all(np.isfinite(matrix)) and np.all(np.isfinite(shifted_costs))):
+                raise FloatingPointError
+        except (FloatingPointError, OverflowError, ValueError):
+            return
+
+        model = highspy.Highs()
+        for name, value in {
+            "output_flag": False,
+            "solver": "simplex",
+            "threads": 1,
+            "primal_feasibility_tolerance": 1e-10,
+            "dual_feasibility_tolerance": 1e-10,
+            "small_matrix_value": 1e-12,
+        }.items():
+            if model.setOptionValue(name, value) == highspy.HighsStatus.kError:
+                return
+        row_count, column_count = matrix.shape
+        lp = highspy.HighsLp()
+        lp.num_col_, lp.num_row_ = column_count, row_count
+        lp.col_cost_ = shifted_costs
+        lp.col_lower_ = np.zeros(column_count)
+        lp.col_upper_ = np.full(column_count, highspy.kHighsInf)
+        rhs = np.r_[np.zeros(row_count - 1), 1.0]
+        lp.row_lower_ = rhs
+        lp.row_upper_ = rhs
+        lp.a_matrix_.format_ = highspy.MatrixFormat.kRowwise
+        lp.a_matrix_.start_ = np.arange(row_count + 1) * column_count
+        lp.a_matrix_.index_ = np.tile(np.arange(column_count), row_count)
+        lp.a_matrix_.value_ = matrix.ravel()
+        if model.passModel(lp) == highspy.HighsStatus.kError:
+            return
+        self._model = model
+        self._origin = origin
+        self._scale = scale
+
+    def solve(
+        self,
+        indices: Sequence[int],
+        origin: tuple[float, ...],
+        offsets: Sequence[float],
+    ) -> tuple[float, tuple[float, ...]] | None:
+        """Return a locally-polished mixture, or ``None`` for the reference solver."""
+        if not indices or self._model is None:
+            return None
+        try:
+            model = self._model
+            current = set(indices)
+            for index in current ^ self._enabled:
+                upper = highspy.kHighsInf if index in current else 0.0
+                if model.changeColBounds(index, 0.0, upper) == highspy.HighsStatus.kError:
+                    self._model = None
+                    return None
+            self._enabled = current
+            rhs = np.r_[
+                (np.asarray(offsets) + (np.asarray(origin) - self._origin)) / self._scale,
+                1.0,
+            ]
+            if not np.all(np.isfinite(rhs)):
+                return None
+            rows = np.arange(len(rhs))
+            if model.changeRowsBounds(len(rhs), rows, rhs, rhs) == highspy.HighsStatus.kError:
+                self._model = None
+                return None
+            if model.run() == highspy.HighsStatus.kError:
+                self._model = None
+                return None
+            if model.getModelStatus() != highspy.HighsModelStatus.kOptimal:
+                return None
+
+            matrix = np.asarray(
+                [[self._points[index][axis] - origin[axis] for index in indices] for axis in range(len(origin))]
+                + [[1.0] * len(indices)],
+                dtype=np.float64,
+            )
+            target = np.asarray([*offsets, 1.0], dtype=np.float64)
+            costs = np.asarray([self._values[index] for index in indices], dtype=np.float64)
+            baseline = float(np.min(costs))
+            objective = costs - baseline
+            if not (np.all(np.isfinite(matrix)) and np.all(np.isfinite(objective))):
+                return None
+            coefficients, target, full_coefficients, full_target = _scaled_independent_equalities(
+                matrix, target, _PIVOT_TOLERANCE
+            )
+            statuses = model.getBasis().col_status
+            basis = [
+                position for position, index in enumerate(indices) if statuses[index] == highspy.HighsBasisStatus.kBasic
+            ]
+            if len(basis) != coefficients.shape[0] or not _basis_is_well_conditioned(
+                coefficients, basis, _PIVOT_TOLERANCE
+            ):
+                return None
+            _, weights = _simplex_iterations(
+                coefficients,
+                target,
+                objective,
+                basis,
+                _PIVOT_TOLERANCE,
+                local_objective_tolerance=True,
+            )
+            if np.any(np.abs(full_coefficients @ weights - full_target) > 100.0 * _PIVOT_TOLERANCE):
+                return None
+            return baseline + float((costs - baseline) @ weights), tuple(float(weight) for weight in weights)
+        except (FloatingPointError, OverflowError, ValueError, RuntimeError, np.linalg.LinAlgError):
+            return None

httk/analyse/generic/_simplex.py

@@ -0,0 +1,282 @@
+"""Private deterministic solver for small equality-constrained linear programs."""
+
+import math
+from collections.abc import Sequence
+
+import numpy as np
+
+_PIVOT_TOLERANCE = 1e-11
+
+
+def _reduced_cost_tolerances(matrix: np.ndarray, costs: np.ndarray, multipliers: np.ndarray) -> np.ndarray:
+    """Return local float64 roundoff bounds for reduced-cost subtractions."""
+    multiplication_terms = np.sum(np.abs(matrix) * np.abs(multipliers)[:, None], axis=0)
+    return 32.0 * np.finfo(np.float64).eps * (np.abs(costs) + multiplication_terms)
+
+
+class _LPInfeasibleError(ValueError):
+    """The equality-constrained linear program has no feasible point."""
+
+
+class _LPUnboundedError(ValueError):
+    """The equality-constrained linear program is unbounded below."""
+
+
+def _basis_is_well_conditioned(matrix: np.ndarray, basis: Sequence[int], tolerance: float) -> bool:
+    """Return whether a candidate basis is numerically safe enough to solve."""
+    if not basis:
+        return True
+    condition = float(np.linalg.cond(matrix[:, basis]))
+    limit = 1.0 / max(tolerance, 100.0 * np.finfo(np.float64).eps)
+    return math.isfinite(condition) and condition <= limit
+
+
+def _matrix_rank(matrix: np.ndarray, threshold: float) -> int:
+    """Return the SVD rank against one absolute singular-value threshold."""
+    if matrix.size == 0:
+        return 0
+    singular_values = np.linalg.svd(matrix, compute_uv=False)
+    return int(np.count_nonzero(singular_values > threshold))
+
+
+def _scaled_independent_equalities(
+    matrix: np.ndarray,
+    rhs: np.ndarray,
+    tolerance: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Scale equalities, reject inconsistency, and retain independent rows."""
+    if matrix.shape[0] == 0:
+        return matrix.copy(), rhs.copy(), matrix.copy(), rhs.copy()
+
+    if matrix.shape[1] == 0:
+        coefficient_sizes = np.zeros(matrix.shape[0], dtype=np.float64)
+    else:
+        coefficient_sizes = np.max(np.abs(matrix), axis=1)
+    row_sizes = np.maximum(coefficient_sizes, np.abs(rhs))
+    row_sizes[row_sizes == 0.0] = 1.0
+    scaled_matrix = matrix / row_sizes[:, None]
+    scaled_rhs = rhs / row_sizes
+    augmented = np.column_stack((scaled_matrix, scaled_rhs))
+    singular_values = np.linalg.svd(augmented, compute_uv=False)
+    largest = float(singular_values[0])
+    rank_threshold = tolerance * max(1.0, largest)
+    coefficient_rank = _matrix_rank(scaled_matrix, rank_threshold)
+    augmented_rank = int(np.count_nonzero(singular_values > rank_threshold))
+    if augmented_rank > coefficient_rank:
+        raise _LPInfeasibleError("linear program is infeasible")
+
+    selected: list[int] = []
+    selected_rank = 0
+    for row in range(scaled_matrix.shape[0]):
+        trial = scaled_matrix[[*selected, row], :]
+        trial_rank = _matrix_rank(trial, rank_threshold)
+        if trial_rank > selected_rank:
+            selected.append(row)
+            selected_rank = trial_rank
+        if selected_rank == coefficient_rank:
+            break
+    if selected_rank != coefficient_rank:
+        raise RuntimeError("could not select independent equality constraints")
+    return (
+        scaled_matrix[selected, :],
+        scaled_rhs[selected],
+        scaled_matrix,
+        scaled_rhs,
+    )
+
+
+def _simplex_iterations(
+    matrix: np.ndarray,
+    rhs: np.ndarray,
+    costs: np.ndarray,
+    basis: list[int],
+    tolerance: float,
+    *,
+    local_objective_tolerance: bool = False,
+) -> tuple[list[int], np.ndarray]:
+    """Run revised-simplex pivots from a feasible basis using Bland's rule."""
+    row_count, variable_count = matrix.shape
+    if row_count == 0:
+        if np.any(costs < 0.0):
+            raise _LPUnboundedError("linear program is unbounded below")
+        return basis, np.zeros(variable_count, dtype=np.float64)
+
+    max_iterations = max(10_000, 100 * (row_count + variable_count))
+    for _ in range(max_iterations):
+        basis_matrix = matrix[:, basis]
+        try:
+            basic_values = np.linalg.solve(basis_matrix, rhs)
+            multipliers = np.linalg.solve(basis_matrix.T, costs[basis])
+        except np.linalg.LinAlgError as exc:
+            raise RuntimeError("simplex basis became singular") from exc
+
+        small_negative = (basic_values < 0.0) & (np.abs(basic_values) <= tolerance)
+        basic_values[small_negative] = 0.0
+        if np.any(basic_values < -tolerance):
+            raise RuntimeError("simplex basis lost primal feasibility")
+
+        reduced_costs = costs - matrix.T @ multipliers
+        reduced_costs[basis] = 0.0
+        reduced_cost_tolerances: float | np.ndarray
+        if local_objective_tolerance:
+            reduced_cost_tolerances = _reduced_cost_tolerances(matrix, costs, multipliers)
+        else:
+            reduced_cost_tolerances = tolerance
+        entering_candidates = np.flatnonzero(reduced_costs < -reduced_cost_tolerances).tolist()
+        if not entering_candidates:
+            solution = np.zeros(variable_count, dtype=np.float64)
+            solution[basis] = basic_values
+            return basis, solution
+
+        pivoted = False
+        for entering in entering_candidates:
+            direction = np.linalg.solve(basis_matrix, matrix[:, entering])
+            eligible = [row for row in range(row_count) if direction[row] > tolerance]
+            if not eligible:
+                raise _LPUnboundedError("linear program is unbounded below")
+
+            ratios = {row: basic_values[row] / direction[row] for row in eligible}
+            minimum = min(ratios.values())
+            machine_tolerance = 16.0 * np.finfo(np.float64).eps
+            minimizers = [
+                row
+                for row in eligible
+                if abs(ratios[row] - minimum) <= machine_tolerance * max(1.0, abs(minimum), abs(ratios[row]))
+            ]
+            for leaving_row in sorted(minimizers, key=basis.__getitem__):
+                candidate_basis = basis.copy()
+                candidate_basis[leaving_row] = entering
+                if not _basis_is_well_conditioned(matrix, candidate_basis, tolerance):
+                    continue
+                basis = candidate_basis
+                pivoted = True
+                break
+            if pivoted:
+                break
+        if not pivoted:
+            raise RuntimeError("simplex found no numerically safe pivot")
+
+    raise RuntimeError("simplex iteration limit exceeded")
+
+
+def _solve_equality_lp(
+    costs: Sequence[float],
+    matrix: Sequence[Sequence[float]],
+    rhs: Sequence[float],
+    *,
+    pivot_tolerance: float = _PIVOT_TOLERANCE,
+) -> tuple[float, tuple[float, ...]]:
+    """Minimize ``costs @ x`` subject to ``matrix @ x == rhs`` and ``x >= 0``.
+
+    This deterministic dense two-phase revised simplex max-scales equality rows,
+    uses SVD rank cleanup, and starts from artificial variables. Both entering and
+    genuinely tied leaving variables follow Bland's anti-cycling rule. Candidate
+    pivots whose bases are too ill-conditioned are skipped.
+
+    The caller may express coordinate constraints relative to an origin. Phase-two
+    reduced-cost tests use local ``float64`` roundoff bounds for each objective
+    subtraction.
+
+    :param costs: Objective coefficients to minimize.
+    :param matrix: Equality-constraint coefficient rows.
+    :param rhs: Target values for the equality constraints.
+    :param pivot_tolerance: Positive threshold for rank, feasibility, and pivot tests.
+    :return: The minimum objective value and corresponding non-negative variable values.
+
+    :raises _LPInfeasibleError: If the equality constraints cannot be satisfied.
+    :raises _LPUnboundedError: If the objective is unbounded below.
+    """
+    tolerance = float(pivot_tolerance)
+    if not math.isfinite(tolerance) or tolerance <= 0.0:
+        raise ValueError("pivot_tolerance must be a finite positive number")
+
+    objective = np.asarray(costs, dtype=np.float64)
+    coefficients = np.asarray(matrix, dtype=np.float64)
+    target = np.asarray(rhs, dtype=np.float64)
+    if objective.ndim != 1 or coefficients.ndim != 2 or target.ndim != 1:
+        raise ValueError("costs and rhs must be vectors and matrix must be two-dimensional")
+    row_count, variable_count = coefficients.shape
+    if objective.shape != (variable_count,) or target.shape != (row_count,):
+        raise ValueError("linear-program dimensions do not agree")
+    if not (np.all(np.isfinite(objective)) and np.all(np.isfinite(coefficients)) and np.all(np.isfinite(target))):
+        raise ValueError("linear-program inputs must be finite")
+    coefficients, target, scaled_coefficients, scaled_target = _scaled_independent_equalities(
+        coefficients,
+        target,
+        tolerance,
+    )
+    row_count = coefficients.shape[0]
+    if variable_count == 0:
+        return 0.0, ()
+
+    negative_rhs = target < 0.0
+    coefficients = coefficients.copy()
+    target = target.copy()
+    coefficients[negative_rhs] *= -1.0
+    target[negative_rhs] *= -1.0
+
+    artificial = np.eye(row_count, dtype=np.float64)
+    phase_one_matrix = np.concatenate((coefficients, artificial), axis=1)
+    phase_one_costs = np.concatenate(
+        (
+            np.zeros(variable_count, dtype=np.float64),
+            np.ones(row_count, dtype=np.float64),
+        )
+    )
+    basis = list(range(variable_count, variable_count + row_count))
+    basis, phase_one_solution = _simplex_iterations(
+        phase_one_matrix,
+        target,
+        phase_one_costs,
+        basis,
+        tolerance,
+    )
+    artificial_sum = float(np.sum(phase_one_solution[variable_count:]))
+    if artificial_sum > tolerance:
+        raise _LPInfeasibleError("linear program is infeasible")
+
+    # A zero artificial basic variable either pivots onto an original column or marks a
+    # redundant equality.
+    while any(index >= variable_count for index in basis):
+        artificial_row = min(
+            (row for row, index in enumerate(basis) if index >= variable_count),
+            key=basis.__getitem__,
+        )
+        basis_matrix = phase_one_matrix[:, basis]
+        tableau_original = np.linalg.solve(basis_matrix, phase_one_matrix[:, :variable_count])
+        basis_set = set(basis)
+        entering_candidates = [
+            index
+            for index in range(variable_count)
+            if index not in basis_set and abs(tableau_original[artificial_row, index]) > tolerance
+        ]
+        pivoted = False
+        for entering in entering_candidates:
+            candidate_basis = basis.copy()
+            candidate_basis[artificial_row] = entering
+            if not _basis_is_well_conditioned(phase_one_matrix, candidate_basis, tolerance):
+                continue
+            basis = candidate_basis
+            pivoted = True
+            break
+        if pivoted:
+            continue
+        if entering_candidates:
+            raise RuntimeError("simplex found no numerically safe artificial-variable pivot")
+        phase_one_matrix = np.delete(phase_one_matrix, artificial_row, axis=0)
+        target = np.delete(target, artificial_row)
+        del basis[artificial_row]
+
+    phase_two_matrix = phase_one_matrix[:, :variable_count]
+    _, solution = _simplex_iterations(
+        phase_two_matrix,
+        target,
+        objective,
+        basis,
+        tolerance,
+        local_objective_tolerance=True,
+    )
+    residual = scaled_coefficients @ solution - scaled_target
+    if np.any(np.abs(residual) > 100.0 * tolerance):
+        raise _LPInfeasibleError("linear program did not reach a feasible point")
+    return float(objective @ solution), tuple(float(value) for value in solution)