dichromatic-map 0.1.0__py3-none-any.whl

dichromatic_map/__init__.py

@@ -0,0 +1,14 @@
+"""DichromaticMap numerical package. Importing it does not load Qt."""
+
+from .crystal import get_geometry, projected_columns
+from .cells import count_cell_atoms
+from .matching import exact_csl_cell, local_near_pairs, same_layer_coincidence_sites
+
+__all__ = [
+    "get_geometry",
+    "projected_columns",
+    "count_cell_atoms",
+    "exact_csl_cell",
+    "local_near_pairs",
+    "same_layer_coincidence_sites",
+]

dichromatic_map/__main__.py

@@ -0,0 +1,88 @@
+"""Command-line entry point; GUI imports happen only when starting a viewer."""
+
+from __future__ import annotations
+import argparse
+import multiprocessing
+import os
+from pathlib import Path
+from .state import PatternParameters
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Standalone FCC/BCC integer-axis tilt-GB viewer; coordinates in a0"
+    )
+    parser.add_argument(
+        "--angle",
+        type=float,
+        default=None,
+        help="degrees; default is Sigma9 for 110, Sigma5 for 100, lowest-Sigma preset otherwise",
+    )
+    parser.add_argument("--lattice", choices=("FCC", "BCC"), default="FCC")
+    parser.add_argument(
+        "--axis",
+        default="110",
+        help='Tilt axis: 100, 110, 111, 112, or an integer triple, e.g. "1 -1 3"',
+    )
+    parser.add_argument(
+        "--lattice-constant",
+        type=float,
+        default=3.52,
+        help="reference a0 in Angstrom; display is normalized by a0",
+    )
+    parser.add_argument(
+        "--width", type=float, default=12.0, help="base view width in a0 (not Angstrom)"
+    )
+    parser.add_argument(
+        "--height",
+        type=float,
+        default=9.0,
+        help="base view height in a0 (not Angstrom)",
+    )
+    parser.add_argument("--marker-size", type=float, default=32.0)
+    parser.add_argument(
+        "--view-scale",
+        type=float,
+        default=1.0,
+        help="initial field-size multiplier, 0.1 to 5 (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=min(4, max(1, os.cpu_count() or 1)),
+        help="calculation processes; use 1 to disable multiprocessing (default: %(default)s)",
+    )
+    parser.add_argument("--save", type=Path, metavar="PNG")
+    return parser.parse_args()
+
+
+def main() -> None:
+    multiprocessing.freeze_support()
+    arguments = parse_arguments()
+    from .ui.controls import create_application
+    from .ui.window import DichromaticPatternWindow
+
+    parameters = PatternParameters(
+        angle_deg=arguments.angle,
+        lattice_constant=arguments.lattice_constant,
+        width=arguments.width,
+        height=arguments.height,
+        marker_size=arguments.marker_size,
+        view_scale=arguments.view_scale,
+        lattice=arguments.lattice,
+        axis=arguments.axis,
+    )
+    application = create_application()
+    window = DichromaticPatternWindow(parameters, worker_count=arguments.workers)
+    window.show()
+    application.processEvents()
+    if arguments.save is not None:
+        window.save(arguments.save)
+        print(f"Saved dichromatic pattern to {arguments.save}")
+        window.close()
+        return
+    raise SystemExit(application.exec())
+
+
+if __name__ == "__main__":
+    main()

dichromatic_map/cells.py

@@ -0,0 +1,287 @@
+"""Cell geometry, common-cell results and whole-region atom counting."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+from .crystal import get_geometry, projected_columns, GeometryLimitError
+
+SIDE_TOLERANCE = 1.0e-9
+
+
+def validate_cell_vertices(vertices):
+    """Four distinct convex vertices in perimeter order, in model coordinates."""
+    vertices = np.asarray(vertices, dtype=float)
+    if vertices.shape != (4, 2) or not np.all(np.isfinite(vertices)):
+        raise ValueError("Select four finite vertices in perimeter order")
+    edges = np.roll(vertices, -1, axis=0) - vertices
+    lengths = np.linalg.norm(edges, axis=1)
+    tolerance = 1e-8 * max(1.0, float(lengths.max()))
+    turns = edges[:, 0] * np.roll(edges[:, 1], -1) - edges[:, 1] * np.roll(
+        edges[:, 0], -1
+    )
+    if np.any(lengths <= tolerance) or not (
+        np.all(turns > tolerance * lengths) or np.all(turns < -tolerance * lengths)
+    ):
+        raise ValueError(
+            "Vertices must form a convex, non-crossing cell; pick them around its perimeter"
+        )
+    return vertices
+
+
+def cell_membership(points, vertices):
+    """Interior, boundary and (if parallelogram) half-open membership masks.
+
+    Half-open means p0 + u*(p1-p0) + v*(p3-p0), 0 <= u,v < 1.
+    It avoids counting the upper two edges twice when cells are repeated.
+    Geometric parallelogram shape does not prove crystal periodicity.
+    """
+    vertices = validate_cell_vertices(vertices)
+    points = np.asarray(points, dtype=float).reshape(-1, 2)
+    edges = np.roll(vertices, -1, axis=0) - vertices
+    lengths = np.linalg.norm(edges, axis=1)
+    tolerance = 1e-8 * max(1.0, float(lengths.max()))
+    orientation = np.sign(np.linalg.det(np.column_stack((edges[0], -edges[-1]))))
+    delta = points[:, None, :] - vertices
+    distances = (
+        orientation
+        * (edges[None, :, 0] * delta[:, :, 1] - edges[None, :, 1] * delta[:, :, 0])
+        / lengths
+    )
+    closed = np.all(distances >= -tolerance, axis=1)
+    interior = np.all(distances > tolerance, axis=1)
+    half_open = None
+    if (
+        np.linalg.norm((vertices[2] - vertices[1]) - (vertices[3] - vertices[0]))
+        <= tolerance
+    ):
+        basis = np.column_stack((vertices[1] - vertices[0], vertices[3] - vertices[0]))
+        inverse = np.linalg.inv(basis)
+        uv = (points - vertices[0]) @ inverse.T
+        eps = tolerance * np.linalg.norm(inverse, axis=1)
+        half_open = np.all((uv >= -eps) & (uv < 1 - eps), axis=1)
+    return interior, closed & ~interior, half_open
+
+
+@dataclass(frozen=True)
+class CellAtomCounts:
+    interior: np.ndarray  # grain x axial layer, one full axial repeat
+    boundary: np.ndarray
+    half_open: np.ndarray | None
+    areas: np.ndarray  # one actual polygon area per grain, a0 squared
+    half_open_available: np.ndarray  # parallelogram test per grain
+    half_open_edges: np.ndarray | None  # unique edge atoms retained
+    half_open_corners: np.ndarray | None  # unique corner atoms retained
+
+    @property
+    def area(self):
+        """Compatibility for a shared-area cell; never average different cells."""
+        if not np.allclose(self.areas, self.areas[0], atol=1e-10, rtol=1e-10):
+            raise ValueError("Grain polygon areas differ; use areas[grain_index]")
+        return float(self.areas[0])
+
+
+def count_cell_atoms(
+    vertices,
+    angle,
+    deformations,
+    lattice="FCC",
+    axis="110",
+    boundary_points=None,
+    region_states=(True, True, True, True),
+    layer=-1,
+    translations=None,
+):
+    """Count the entire selected cell, independently of viewport and rendering.
+
+    Vertices may be one shared (4,2) polygon or two independent (2,4,2)
+    polygons built from each grain's actual atom positions. Each grain is
+    counted inside its own polygon; the viewer passes the picked layer.
+    layer=-1 retains all-layer counting for non-GUI callers.
+    Generation uses the same interactive allocation guard as normal rendering.
+    """
+    vertices = np.asarray(vertices, dtype=float)
+    if vertices.shape == (4, 2):
+        vertices = np.stack((vertices, vertices))
+    if vertices.shape != (2, 4, 2):
+        raise ValueError("Provide a (4,2) common polygon or (2,4,2) grain polygons")
+    for polygon in vertices:
+        validate_cell_vertices(polygon)
+    geometry = get_geometry(lattice, axis)
+    if (
+        not isinstance(layer, (int, np.integer))
+        or not -1 <= layer < geometry.layer_count
+    ):
+        raise ValueError("Count layer must be -1 or a valid axial layer index")
+    inside_counts = np.zeros((2, geometry.layer_count), dtype=int)
+    translations = (
+        np.zeros((2, 2))
+        if translations is None
+        else np.asarray(translations, dtype=float)
+    )
+    if translations.shape != (2, 2) or not np.all(np.isfinite(translations)):
+        raise ValueError("Provide two finite grain translations")
+    edge_counts = np.zeros_like(inside_counts)
+    half_counts = np.zeros_like(inside_counts)
+    half_edge_counts = np.zeros_like(inside_counts)
+    half_corner_counts = np.zeros_like(inside_counts)
+    is_parallelogram = np.zeros(2, dtype=bool)
+    areas = np.zeros(2)
+    for grain_index, sign in enumerate((1, -1)):
+        polygon = vertices[grain_index]
+        low, high = polygon.min(axis=0), polygon.max(axis=0)
+        margin = 1e-7 * max(1.0, float(np.max(high - low)))
+        width, height = high - low + 2 * margin
+        center = (low + high) / 2
+        try:
+            grain = projected_columns(
+                width,
+                height,
+                sign * angle / 2,
+                center,
+                deformations[grain_index],
+                lattice,
+                axis,
+                translations[grain_index],
+            )
+        except GeometryLimitError as error:
+            raise GeometryLimitError(
+                "Manual cell exceeds the atom enumeration limit; select a smaller cell. "
+                "View zoom does not affect counting."
+            ) from error
+        # A manual cell belongs to one axial layer. Filter before polygon and
+        # corner distance calculations, which otherwise process every layer.
+        selected = grain.layers == layer if layer >= 0 else slice(None)
+        positions = grain.positions[selected]
+        layers = grain.layers[selected]
+        inside, boundary, half_open = cell_membership(positions, polygon)
+        half_open_edges = None
+        half_open_corners = None
+        if half_open is not None:
+            corner_tolerance = 1e-8 * max(1.0, float(np.max(high - low)))
+            at_corner = np.any(
+                np.linalg.norm(
+                    positions[:, None, :] - polygon[None, :, :], axis=2
+                )
+                <= corner_tolerance,
+                axis=1,
+            )
+            half_open_corners = half_open & at_corner
+            half_open_edges = half_open & boundary & ~at_corner
+        visible = np.ones(len(positions), dtype=bool)
+        if boundary_points is not None and len(boundary_points) == 2:
+            start, end = np.asarray(boundary_points)
+            direction = end - start
+            cross = direction[0] * (positions[:, 1] - start[1]) - direction[1] * (
+                positions[:, 0] - start[0]
+            )
+            visible &= (region_states[2 * grain_index] & (cross >= -1e-9)) | (
+                region_states[2 * grain_index + 1] & (cross <= 1e-9)
+            )
+        for mask, counts in (
+            (inside, inside_counts),
+            (boundary, edge_counts),
+            (half_open, half_counts),
+            (half_open_edges, half_edge_counts),
+            (half_open_corners, half_corner_counts),
+        ):
+            if mask is not None:
+                counts[grain_index] = np.bincount(
+                    layers[mask & visible], minlength=geometry.layer_count
+                )
+        is_parallelogram[grain_index] = half_open is not None
+        # Translation-stable area of this grain's actual polygon.
+        relative = polygon - polygon[0]
+        areas[grain_index] = (
+            abs(
+                np.sum(
+                    relative[:, 0] * np.roll(relative[:, 1], -1)
+                    - relative[:, 1] * np.roll(relative[:, 0], -1)
+                )
+            )
+            / 2
+        )
+    half_open_result = np.any(is_parallelogram)
+    return CellAtomCounts(
+        interior=inside_counts,
+        boundary=edge_counts,
+        half_open=half_counts if half_open_result else None,
+        areas=areas,
+        half_open_available=is_parallelogram,
+        half_open_edges=half_edge_counts if half_open_result else None,
+        half_open_corners=half_corner_counts if half_open_result else None,
+    )
+
+
+def selected_region_mask(
+    points: np.ndarray,
+    first: np.ndarray,
+    second: np.ndarray,
+    keep_left: bool,
+    keep_right: bool,
+) -> np.ndarray:
+    direction = second - first
+    signed_cross_product = direction[0] * (points[:, 1] - first[1]) - direction[1] * (
+        points[:, 0] - first[0]
+    )
+    keep = np.zeros(len(points), dtype=bool)
+    if keep_left:
+        keep |= signed_cross_product >= -SIDE_TOLERANCE
+    if keep_right:
+        keep |= signed_cross_product <= SIDE_TOLERANCE
+    return keep
+
+
+def bases(angle, lattice="FCC", axis="110"):
+    t = np.deg2rad(angle / 2)
+    c, s = np.cos(t), np.sin(t)
+    r = np.array([[c, -s], [s, c]])
+    b = get_geometry(lattice, axis).planar_basis
+    return r @ b, r.T @ b
+
+
+def determinant(m):
+    return int(m[0, 0] * m[1, 1] - m[0, 1] * m[1, 0])
+
+
+@dataclass(frozen=True)
+class StrainedCell:
+    m1: np.ndarray
+    m2: np.ndarray
+    f1: np.ndarray
+    f2: np.ndarray
+    cell: np.ndarray  # columns, laboratory projection, in units of a0
+    max_strain: float
+    lattice: str = "FCC"
+    axis: str = "110"
+
+    @property
+    def atoms(self):
+        layers = get_geometry(self.lattice, self.axis).layer_count
+        return tuple(layers * abs(determinant(m)) for m in (self.m1, self.m2))
+
+    def label(self):
+        n1, n2 = self.atoms
+        return f"{n1}/{n2} atoms | max strain {100*self.max_strain:.3f}%"
+
+
+def reduce_cell(m1, m2, cell):
+    """Gauss-reduce common vectors with identical integer column operations."""
+    m1, m2, cell = m1.copy(), m2.copy(), cell.copy()
+    for _ in range(64):
+        if np.dot(cell[:, 1], cell[:, 1]) < np.dot(cell[:, 0], cell[:, 0]):
+            cell = cell[:, ::-1]
+            m1 = m1[:, ::-1]
+            m2 = m2[:, ::-1]
+        q = int(
+            np.rint(np.dot(cell[:, 0], cell[:, 1]) / np.dot(cell[:, 0], cell[:, 0]))
+        )
+        if q == 0:
+            break
+        cell[:, 1] -= q * cell[:, 0]
+        m1[:, 1] -= q * m1[:, 0]
+        m2[:, 1] -= q * m2[:, 0]
+    if np.linalg.det(cell) < 0:
+        cell[:, 1] *= -1
+        m1[:, 1] *= -1
+        m2[:, 1] *= -1
+    return m1, m2, cell

dichromatic_map/compute.py

@@ -0,0 +1,257 @@
+"""Qt-free worker entry points, executor ownership and asynchronous search.
+
+Workers are module-level functions so a spawned process imports numerical
+modules only. The UI coordinates operations and polls completed futures.
+"""
+
+from __future__ import annotations
+from collections import deque
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
+import multiprocessing
+import os
+import numpy as np
+from .crystal import ProjectedGrain, projected_columns, get_geometry
+from .cells import count_cell_atoms
+from .matching import local_near_pairs, same_layer_coincidence_sites
+from .strain import candidate_vectors, solve_cells_chunk, pareto_cells
+
+
+def worker_initializer():
+    """Avoid each process starting its own BLAS thread team when available."""
+    global _blas_limit
+    try:
+        from threadpoolctl import threadpool_limits
+
+        _blas_limit = threadpool_limits(limits=1)
+    except ImportError:
+        pass  # NumPy-only installations remain supported.
+
+
+def local_match_layers_worker(grain1, grain2, distance, layers):
+    return os.getpid(), local_near_pairs(grain1, grain2, distance, layers)
+
+
+def cell_count_worker(*args):
+    return os.getpid(), count_cell_atoms(*args)
+
+
+def generate_grain_worker(
+    width: float,
+    height: float,
+    rotation_deg: float,
+    center: tuple[float, float],
+    deformation: np.ndarray | None = None,
+    lattice: str = "FCC",
+    axis: str = "110",
+    translation: np.ndarray | None = None,
+) -> tuple[int, ProjectedGrain]:
+    """Process-pool entry point for one projected grain."""
+
+    return (
+        os.getpid(),
+        projected_columns(
+            width, height, rotation_deg, center, deformation, lattice, axis, translation
+        ),
+    )
+
+
+def coincidence_layer_worker(
+    grain_1: ProjectedGrain,
+    grain_2: ProjectedGrain,
+    tolerance: float,
+    layer: int,
+) -> tuple[int, np.ndarray]:
+    """Process-pool entry point for one stacking-layer coincidence search."""
+
+    only_first = grain_1.layers == layer
+    only_second = grain_2.layers == layer
+    first = ProjectedGrain(
+        grain_1.positions[only_first],
+        np.zeros(np.count_nonzero(only_first), dtype=np.int16),
+        grain_1.half_indices[only_first],
+    )
+    second = ProjectedGrain(
+        grain_2.positions[only_second],
+        np.zeros(np.count_nonzero(only_second), dtype=np.int16),
+        grain_2.half_indices[only_second],
+    )
+    return os.getpid(), same_layer_coincidence_sites(first, second, tolerance)[0]
+
+
+def coincidence_layers_worker(grain_1, grain_2, tolerance, layers):
+    """A bounded batch of phases, avoiding one full-array transfer per layer."""
+    return os.getpid(), tuple(
+        (
+            int(layer),
+            coincidence_layer_worker(grain_1, grain_2, tolerance, int(layer))[1],
+        )
+        for layer in layers
+    )
+
+
+class NearSearch:
+    """Bounded asynchronous search; stale requests never publish results.
+
+    Preparation and pair solves run off the UI thread. At most workers jobs
+    are in flight. Invalidation drops pending jobs and lets bounded running
+    chunks finish before submitting the next request.
+    """
+
+    def __init__(self, workers=1, executor=None):
+        self.workers = max(1, int(workers))
+        self.executor = executor
+        self.owns_executor = executor is None
+        self.generation = 0
+        self.jobs = deque()
+        self.running = {}
+        self.parts = {}
+        self.total = self.completed = 0
+        self.busy = False
+        self.error = None
+        self.process_ids = set()
+
+    def cancel(self):
+        self.generation += 1
+        self.jobs.clear()
+        self.parts.clear()
+        self.busy = False
+        self.error = None
+        self.total = self.completed = 0
+        for future in self.running:
+            future.cancel()
+
+    def request(self, angle, percent, extent, lattice="FCC", axis="110"):
+        self.cancel()
+        geometry = get_geometry(lattice, axis)
+        if self.executor is None:
+            self.executor = (
+                ProcessPoolExecutor(
+                    max_workers=self.workers,
+                    mp_context=multiprocessing.get_context("spawn"),
+                    initializer=worker_initializer,
+                )
+                if self.workers > 1
+                else ThreadPoolExecutor(max_workers=1)
+            )
+        self.args = (angle, percent, extent, geometry.lattice, geometry.axis)
+        self.jobs.append(("prepare", candidate_vectors, self.args))
+        self.busy = True
+
+    def poll(self):
+        try:
+            for future in list(self.running):
+                if not future.done():
+                    continue
+                generation, stage, start = self.running.pop(future)
+                if generation != self.generation:
+                    continue
+                result = future.result()
+                if stage == "prepare":
+                    i, j = result
+                    for start in range(0, len(i), 8):
+                        self.jobs.append(
+                            (
+                                "solve",
+                                solve_cells_chunk,
+                                (
+                                    self.args[0],
+                                    self.args[1],
+                                    i,
+                                    j,
+                                    start,
+                                    start + 8,
+                                    self.args[3],
+                                    self.args[4],
+                                ),
+                            )
+                        )
+                    self.total = len(self.jobs)
+                else:
+                    pid, cells = result
+                    self.process_ids.add(pid)
+                    self.parts[start] = cells
+                    self.completed += 1
+            while self.jobs and len(self.running) < self.workers:
+                stage, function, args = self.jobs.popleft()
+                future = self.executor.submit(function, *args)
+                self.running[future] = (
+                    self.generation, stage, args[4] if stage == "solve" else -1
+                )
+            if self.busy and not self.jobs and not self.running:
+                # Equal-area/strain candidates retain serial search order,
+                # independently of which process happens to finish first.
+                result = pareto_cells([
+                    cell for start in sorted(self.parts) for cell in self.parts[start]
+                ])
+                self.parts.clear()
+                self.busy = False
+                return result
+        except Exception as error:
+            self.cancel()
+            self.error = str(error)
+        return None
+
+    def close(self):
+        self.cancel()
+        if self.owns_executor and self.executor is not None:
+            self.executor.shutdown(wait=False, cancel_futures=True)
+        self.executor = None
+
+
+class ComputeSession:
+    """Own the shared executors and pending work for one viewer session."""
+
+    def __init__(self):
+        self.worker_count = 1
+        self.executor = None
+        self.local_thread_executor = None
+        self.near_search = None
+        self.parallel_stage = None
+        self.parallel_futures = []
+        self.parallel_payload = {}
+        self.parallel_generation = 0
+        self.worker_process_ids = set()
+        self.manual_count_future = None
+        self.manual_count_pending = None
+        self.manual_count_running_key = None
+
+    def configure(self, worker_count):
+        old_executor, self.executor = self.executor, None
+        if old_executor is not None:
+            old_executor.shutdown(wait=False, cancel_futures=True)
+        self.worker_count = int(worker_count)
+        if self.worker_count > 1:
+            self.executor = ProcessPoolExecutor(
+                max_workers=self.worker_count,
+                mp_context=multiprocessing.get_context("spawn"),
+                initializer=worker_initializer,
+            )
+
+    def background_executor(self):
+        if self.executor is not None:
+            return self.executor
+        if self.local_thread_executor is None:
+            self.local_thread_executor = ThreadPoolExecutor(max_workers=1)
+        return self.local_thread_executor
+
+    def cancel_parallel(self):
+        self.parallel_generation += 1
+        for future in self.parallel_futures:
+            future.cancel()
+        self.parallel_futures = []
+        self.parallel_stage = None
+        self.parallel_payload = {}
+
+    def close(self):
+        self.manual_count_pending = None
+        if self.manual_count_future is not None:
+            self.manual_count_future.cancel()
+        if self.near_search is not None:
+            self.near_search.close()
+        self.cancel_parallel()
+        executor, self.executor = self.executor, None
+        if executor is not None:
+            executor.shutdown(wait=False, cancel_futures=True)
+        if self.local_thread_executor is not None:
+            self.local_thread_executor.shutdown(wait=False, cancel_futures=True)
+            self.local_thread_executor = None