dichromatic-map 0.1.0__tar.gz

dichromatic_map-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to DichromaticMap
+
+Bug reports, documentation improvements and code contributions are welcome.
+This is a volunteer-developed project. External donations are not currently
+accepted.
+
+## Report a problem or request a feature
+
+Open a [GitHub issue](https://github.com/Yazhuo-Liu/DichromaticMap/issues) or
+email [yliu3500@gatech.edu](mailto:yliu3500@gatech.edu).
+
+For a bug report, include:
+
+- The DichromaticMap version or commit, Python version and operating system.
+- The relevant settings: lattice, tilt axis, misorientation, visible layers,
+  Near-CSL method and parameters, and worker count when applicable.
+- A small reproducible example or numbered GUI steps.
+- The expected result and the actual result, including any error message.
+- A screenshot or exported figure when it helps explain a display problem.
+
+For a numerical discrepancy, include the input values, units and reference
+result or calculation used for comparison. For a feature request, explain the
+intended task and the behavior that would help accomplish it.
+
+## Propose a change
+
+Submit a [pull request](https://github.com/Yazhuo-Liu/DichromaticMap/pulls), or
+email a description of the change and a patch or repository link to
+[yliu3500@gatech.edu](mailto:yliu3500@gatech.edu). An issue or email can also be
+used to discuss a substantial algorithm or API change before implementation.
+
+Keep each contribution focused and describe the problem, the resulting
+behavior and how it was checked. For code changes:
+
+- Preserve scientific conventions, including units, layer identity, coordinate
+  frames, strain definitions and numerical tolerances. Explain any intended
+  change to those conventions and provide a reference or derivation.
+- Add or update meaningful tests for changed behavior. Numerical changes should
+  cover representative geometries and relevant boundary cases; GUI changes
+  should cover the affected interaction or state transition.
+- Update the English and Chinese user guides when usage or results change, and
+  the implementation documents when algorithms or conventions change.
+- Run the relevant test suites and report the results in the pull request,
+  including any checks that could not be run.
+
+Algorithm descriptions are available in the
+[English implementation details](docs/en/development.md) and
+[中文开发细节](docs/zh/development.md).
+
+## Install and run the tests
+
+From the repository root, install the editable package with its test and GUI
+requirements:
+
+```bash
+python -m pip install -e ".[test,gui]"
+python scripts/run_tests.py
+```
+
+Run individual suites when working on a specific part of the project:
+
+```bash
+python scripts/run_tests.py --suite core
+python scripts/run_tests.py --suite gui
+python scripts/run_tests.py --suite packaging
+```
+
+The `core` suite checks numerical behavior and does not depend on the GUI.
+The `gui` suite requires PySide6 and PyQtGraph and uses Qt's `offscreen`
+platform, so it does not require a display server. The `packaging` suite checks
+the distributable package and keeps build artifacts in temporary directories.
+The default command runs all suites.
+
+Tests remain in the source repository for contributors; they are not installed
+with the end-user wheel. Keep generated build artifacts out of contributions.
+
+## 中文说明
+
+问题反馈请使用 [GitHub Issues](https://github.com/Yazhuo-Liu/DichromaticMap/issues)
+或邮件 [yliu3500@gatech.edu](mailto:yliu3500@gatech.edu)，并提供版本、平台、复现步骤、
+预期与实际结果。贡献可提交 PR，也可邮件发送修改说明及补丁或仓库链接。
+涉及算法的修改请说明科学依据，补充相关测试，并同步中英文文档。
+本项目由志愿开发维护，暂不接受外部捐赠。

dichromatic_map-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Yazhuo Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

dichromatic_map-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include main.py
+include CONTRIBUTING.md
+include scripts/run_tests.py
+recursive-include tests *.py
+recursive-include docs *.md *.png

dichromatic_map-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: dichromatic-map
+Version: 0.1.0
+Summary: Layer-resolved cubic tilt grain-boundary dichromatic patterns
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: gui
+Requires-Dist: PySide6; extra == "gui"
+Requires-Dist: pyqtgraph; extra == "gui"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: setuptools>=77.0.3; extra == "test"
+Requires-Dist: wheel; extra == "test"
+Requires-Dist: packaging>=22; extra == "test"
+Dynamic: license-file
+
+# DichromaticMap
+
+[English user guide](docs/en/README.md) · [中文使用手册](docs/zh/README.md)
+
+DichromaticMap provides a Python library and an interactive viewer for
+layer-resolved FCC/BCC tilt grain-boundary dichromatic patterns. Use it to
+inspect two overlaid grains, identify coincidence sites, measure crystal
+vectors, count atoms in selected cells and explore common cells under uniform
+strain.
+
+## Features
+
+- FCC/BCC lattices with ⟨100⟩, ⟨110⟩, ⟨111⟩, ⟨112⟩ and custom integer tilt axes.
+- Independent grain/layer visibility, grain-boundary side filtering and
+  display rotation.
+- Same-layer exact coincidence-site lattice (CSL) detection and local near-pair
+  matching.
+- Vector measurements in both grain coordinate frames, including axial
+  periodic images.
+- Manual common cells with separate G1/G2 atom counts and optional uniform
+  strain fitting.
+- Automatic homogeneous-strain common-cell search and PNG export.
+- NumPy-based numerical functions usable independently of the viewer.
+
+Coordinates and distances use the reference lattice constant a₀ as their unit.
+Local matching preserves the atom positions. Strain operations impose a
+geometric deformation; they do not perform atomic relaxation or minimize
+elastic energy. A manually selected polygon alone does not establish crystal
+periodicity.
+
+## Install and launch
+
+Requires Python 3.10 or later. Download the project, open its root directory,
+and install the library with its viewer:
+
+```bash
+python -m pip install ".[gui]"
+python -m dichromatic_map
+```
+
+The viewer uses PySide6 and PyQtGraph. For numerical calculations only, install
+with `python -m pip install .`; the numerical library requires only NumPy.
+
+```bash
+python -m dichromatic_map --lattice BCC --axis 100
+python -m dichromatic_map --axis "1 -1 3" --workers 4
+python -m dichromatic_map --angle 22 --save pattern.png
+python -m dichromatic_map --help
+```
+
+`dichromatic-map` is an equivalent launch command. From the project root,
+`python main.py` also launches the viewer.
+
+## GUI quick start
+
+![DichromaticMap viewer with its plot and controls](docs/images/gui-overview.png)
+
+The example above shows FCC ⟨110⟩ at the Σ9 preset. The plot is on the left;
+settings and results are in the scrollable **Controls** panel on the right.
+Click section headers to expand them, and switch between the **ORIENTATION**
+and **LAYERS** tabs at the top. Blue markers represent G1, orange outlines
+represent G2, marker shapes distinguish axial layers, and gold outlines mark
+same-layer exact coincidences.
+
+1. **Choose the grains.** In **ORIENTATION**, select **Structure** and
+   **Tilt / viewing axis**, then choose a **CSL preset** or enter a
+   **Misorientation**. For a custom axis, choose **Custom [h k l]**, enter an
+   integer triple such as `1 -1 3`, and click **Apply axis** or press Enter.
+   **Display rotation** turns the drawing without changing the grain geometry.
+2. **Choose visible layers.** Open **LAYERS** and toggle individual **G1 A**,
+   **G2 A**, etc. For a first selection, click **No layers**, then enable
+   **G1 A** and **G2 A**. Coincidence and local-pair markers require the layer to
+   be visible in both grains. Enable **Automatic common cell** to display an
+   available exact or strain-search cell; **Fit cell** frames it in the view.
+3. **Navigate.** Drag to pan and use the wheel to zoom. Under **VIEW /
+   PERFORMANCE → VIEW**, **Field size** selects a wider or narrower region;
+   **Center view** (`C`) returns to the origin at the current zoom. The
+   **PERFORMANCE** tab contains **CPU workers**.
+4. **Measure a vector.** In **GB / VECTOR**, click **Measure vector** (`V`),
+   then click two distinct visible atom positions, P1 and P2. Read the vector
+   annotation at the lower left of the plot. Same-grain picks show that grain's
+   coordinates; cross-grain picks show both G1 and G2 representations.
+   **P2 axial periodic image** selects an axial repeat for the second endpoint
+   without adding plotted atoms.
+5. **Define a boundary.** Click **Pick GB** (`R`) and select B1, then B2.
+   The side switches appear after the second pick; left/right are relative to
+   B1 → B2. Use `1` or `2` for the two complementary grain-side arrangements,
+   and `F` to show all sides again. Layer visibility settings still apply.
+6. **Select and count a cell.** Expand **MANUAL COMMON CELL**, click
+   **Pick 4 CSL vertices** (`M`), and select four gold sites of one layer in
+   clockwise or counterclockwise order around a convex cell. Use **Undo
+   vertex**, **Clear** or **Fit** as needed. The readout gives G1/G2 counts for
+   the complete selected cell, including portions outside the current view.
+   **Apply GB side visibility to counts** optionally restricts those counts
+   to the displayed grain sides.
+7. **Export the figure.** Scroll to **Export plot as PNG…**, choose a file
+   name and save. The PNG contains the plot with its current layers, rotation
+   and annotations; the controls are excluded.
+
+Press `Esc` to stop picking while retaining existing selections. Pressing `R`
+or `V` starts a fresh boundary or vector selection. Click near a visible atom
+or eligible cell marker; background clicks do not create arbitrary vertices.
+
+For inexact orientations, expand **NEAR-CSL**, select a **Method**, and click
+**Enable Near-CSL**:
+
+| Method | How to use it | Effect |
+| --- | --- | --- |
+| **Local matching · no bulk strain** | Adjust **Local pair distance**; inspect purple midpoint markers and use them for manual cell picks | Finds nearby same-layer pairs while preserving the atom positions |
+| **Homogeneous strain + periodic cell** | Set **Max principal strain** and **Search index bound**, then choose a returned candidate | Automatically applies the first result, or the candidate you select, to both grains |
+
+A manually selected local cell containing at least one near pair can also be
+fitted with **Apply bulk strain to selected cell** in **MANUAL COMMON CELL**.
+Set its strain and rotation limits before applying; **Restore original local
+structure** returns to the original geometry. This operation has a separate
+apply step from the automatic search.
+
+For control-by-control instructions, selection rules, result interpretation
+and troubleshooting, see the [English GUI guide](docs/en/README.md#gui-overview)
+or [中文 GUI 使用指南](docs/zh/README.md#gui-overview). Detailed workflows cover
+[vector measurements](docs/en/README.md#gui-vector),
+[Near-CSL methods](docs/en/README.md#gui-near-csl), and
+[manual cells and counts](docs/en/README.md#gui-manual-cell).
+
+## Python usage
+
+```python
+from dichromatic_map import get_geometry, projected_columns, local_near_pairs
+
+geometry = get_geometry("FCC", "110")
+grain1 = projected_columns(12, 9, rotation_deg=11, lattice="FCC", axis="110")
+grain2 = projected_columns(12, 9, rotation_deg=-11, lattice="FCC", axis="110")
+pairs = local_near_pairs(grain1, grain2, distance=0.05)
+
+print("Axial layers:", geometry.layer_count)
+print("Near pairs:", len(pairs.layers))
+print("Pair separations / a0:", pairs.distances)
+```
+
+The grains above have a reference misorientation of 22°. Matching uses the
+supplied projected columns and preserves their layer labels.
+
+| Function exported by `dichromatic_map` | Purpose |
+| --- | --- |
+| `get_geometry` | Obtain planar geometry, axial layers and repeat distance |
+| `projected_columns` | Generate a grain's projected columns in a rectangular region |
+| `same_layer_coincidence_sites` | Locate same-layer coincidences within a specified tolerance |
+| `local_near_pairs` | Find same-layer mutual nearest pairs within a distance threshold |
+| `exact_csl_cell` | Obtain a layer-preserving common translation cell for a recognized commensurate angle |
+| `count_cell_atoms` | Count atoms in complete shared or per-grain polygons |
+
+## Documentation
+
+| Topic | English | 中文 |
+| --- | --- | --- |
+| Installation, viewer workflows and Python API | [User guide](docs/en/README.md) | [使用手册](docs/zh/README.md) |
+| Algorithms, numerical conventions and implementation | [Implementation details](docs/en/development.md) | [开发细节](docs/zh/development.md) |
+
+## Contributing and support
+
+Report problems through [GitHub Issues](https://github.com/Yazhuo-Liu/DichromaticMap/issues)
+or [yliu3500@gatech.edu](mailto:yliu3500@gatech.edu). Contributions can be
+submitted as a pull request or by email; see the [contribution guide](CONTRIBUTING.md).
+This project is developed by volunteers and does not currently accept external
+donations.
+
+## License
+
+DichromaticMap is distributed under the [MIT License](LICENSE).

dichromatic_map-0.1.0/README.md

@@ -0,0 +1,169 @@
+# DichromaticMap
+
+[English user guide](docs/en/README.md) · [中文使用手册](docs/zh/README.md)
+
+DichromaticMap provides a Python library and an interactive viewer for
+layer-resolved FCC/BCC tilt grain-boundary dichromatic patterns. Use it to
+inspect two overlaid grains, identify coincidence sites, measure crystal
+vectors, count atoms in selected cells and explore common cells under uniform
+strain.
+
+## Features
+
+- FCC/BCC lattices with ⟨100⟩, ⟨110⟩, ⟨111⟩, ⟨112⟩ and custom integer tilt axes.
+- Independent grain/layer visibility, grain-boundary side filtering and
+  display rotation.
+- Same-layer exact coincidence-site lattice (CSL) detection and local near-pair
+  matching.
+- Vector measurements in both grain coordinate frames, including axial
+  periodic images.
+- Manual common cells with separate G1/G2 atom counts and optional uniform
+  strain fitting.
+- Automatic homogeneous-strain common-cell search and PNG export.
+- NumPy-based numerical functions usable independently of the viewer.
+
+Coordinates and distances use the reference lattice constant a₀ as their unit.
+Local matching preserves the atom positions. Strain operations impose a
+geometric deformation; they do not perform atomic relaxation or minimize
+elastic energy. A manually selected polygon alone does not establish crystal
+periodicity.
+
+## Install and launch
+
+Requires Python 3.10 or later. Download the project, open its root directory,
+and install the library with its viewer:
+
+```bash
+python -m pip install ".[gui]"
+python -m dichromatic_map
+```
+
+The viewer uses PySide6 and PyQtGraph. For numerical calculations only, install
+with `python -m pip install .`; the numerical library requires only NumPy.
+
+```bash
+python -m dichromatic_map --lattice BCC --axis 100
+python -m dichromatic_map --axis "1 -1 3" --workers 4
+python -m dichromatic_map --angle 22 --save pattern.png
+python -m dichromatic_map --help
+```
+
+`dichromatic-map` is an equivalent launch command. From the project root,
+`python main.py` also launches the viewer.
+
+## GUI quick start
+
+![DichromaticMap viewer with its plot and controls](docs/images/gui-overview.png)
+
+The example above shows FCC ⟨110⟩ at the Σ9 preset. The plot is on the left;
+settings and results are in the scrollable **Controls** panel on the right.
+Click section headers to expand them, and switch between the **ORIENTATION**
+and **LAYERS** tabs at the top. Blue markers represent G1, orange outlines
+represent G2, marker shapes distinguish axial layers, and gold outlines mark
+same-layer exact coincidences.
+
+1. **Choose the grains.** In **ORIENTATION**, select **Structure** and
+   **Tilt / viewing axis**, then choose a **CSL preset** or enter a
+   **Misorientation**. For a custom axis, choose **Custom [h k l]**, enter an
+   integer triple such as `1 -1 3`, and click **Apply axis** or press Enter.
+   **Display rotation** turns the drawing without changing the grain geometry.
+2. **Choose visible layers.** Open **LAYERS** and toggle individual **G1 A**,
+   **G2 A**, etc. For a first selection, click **No layers**, then enable
+   **G1 A** and **G2 A**. Coincidence and local-pair markers require the layer to
+   be visible in both grains. Enable **Automatic common cell** to display an
+   available exact or strain-search cell; **Fit cell** frames it in the view.
+3. **Navigate.** Drag to pan and use the wheel to zoom. Under **VIEW /
+   PERFORMANCE → VIEW**, **Field size** selects a wider or narrower region;
+   **Center view** (`C`) returns to the origin at the current zoom. The
+   **PERFORMANCE** tab contains **CPU workers**.
+4. **Measure a vector.** In **GB / VECTOR**, click **Measure vector** (`V`),
+   then click two distinct visible atom positions, P1 and P2. Read the vector
+   annotation at the lower left of the plot. Same-grain picks show that grain's
+   coordinates; cross-grain picks show both G1 and G2 representations.
+   **P2 axial periodic image** selects an axial repeat for the second endpoint
+   without adding plotted atoms.
+5. **Define a boundary.** Click **Pick GB** (`R`) and select B1, then B2.
+   The side switches appear after the second pick; left/right are relative to
+   B1 → B2. Use `1` or `2` for the two complementary grain-side arrangements,
+   and `F` to show all sides again. Layer visibility settings still apply.
+6. **Select and count a cell.** Expand **MANUAL COMMON CELL**, click
+   **Pick 4 CSL vertices** (`M`), and select four gold sites of one layer in
+   clockwise or counterclockwise order around a convex cell. Use **Undo
+   vertex**, **Clear** or **Fit** as needed. The readout gives G1/G2 counts for
+   the complete selected cell, including portions outside the current view.
+   **Apply GB side visibility to counts** optionally restricts those counts
+   to the displayed grain sides.
+7. **Export the figure.** Scroll to **Export plot as PNG…**, choose a file
+   name and save. The PNG contains the plot with its current layers, rotation
+   and annotations; the controls are excluded.
+
+Press `Esc` to stop picking while retaining existing selections. Pressing `R`
+or `V` starts a fresh boundary or vector selection. Click near a visible atom
+or eligible cell marker; background clicks do not create arbitrary vertices.
+
+For inexact orientations, expand **NEAR-CSL**, select a **Method**, and click
+**Enable Near-CSL**:
+
+| Method | How to use it | Effect |
+| --- | --- | --- |
+| **Local matching · no bulk strain** | Adjust **Local pair distance**; inspect purple midpoint markers and use them for manual cell picks | Finds nearby same-layer pairs while preserving the atom positions |
+| **Homogeneous strain + periodic cell** | Set **Max principal strain** and **Search index bound**, then choose a returned candidate | Automatically applies the first result, or the candidate you select, to both grains |
+
+A manually selected local cell containing at least one near pair can also be
+fitted with **Apply bulk strain to selected cell** in **MANUAL COMMON CELL**.
+Set its strain and rotation limits before applying; **Restore original local
+structure** returns to the original geometry. This operation has a separate
+apply step from the automatic search.
+
+For control-by-control instructions, selection rules, result interpretation
+and troubleshooting, see the [English GUI guide](docs/en/README.md#gui-overview)
+or [中文 GUI 使用指南](docs/zh/README.md#gui-overview). Detailed workflows cover
+[vector measurements](docs/en/README.md#gui-vector),
+[Near-CSL methods](docs/en/README.md#gui-near-csl), and
+[manual cells and counts](docs/en/README.md#gui-manual-cell).
+
+## Python usage
+
+```python
+from dichromatic_map import get_geometry, projected_columns, local_near_pairs
+
+geometry = get_geometry("FCC", "110")
+grain1 = projected_columns(12, 9, rotation_deg=11, lattice="FCC", axis="110")
+grain2 = projected_columns(12, 9, rotation_deg=-11, lattice="FCC", axis="110")
+pairs = local_near_pairs(grain1, grain2, distance=0.05)
+
+print("Axial layers:", geometry.layer_count)
+print("Near pairs:", len(pairs.layers))
+print("Pair separations / a0:", pairs.distances)
+```
+
+The grains above have a reference misorientation of 22°. Matching uses the
+supplied projected columns and preserves their layer labels.
+
+| Function exported by `dichromatic_map` | Purpose |
+| --- | --- |
+| `get_geometry` | Obtain planar geometry, axial layers and repeat distance |
+| `projected_columns` | Generate a grain's projected columns in a rectangular region |
+| `same_layer_coincidence_sites` | Locate same-layer coincidences within a specified tolerance |
+| `local_near_pairs` | Find same-layer mutual nearest pairs within a distance threshold |
+| `exact_csl_cell` | Obtain a layer-preserving common translation cell for a recognized commensurate angle |
+| `count_cell_atoms` | Count atoms in complete shared or per-grain polygons |
+
+## Documentation
+
+| Topic | English | 中文 |
+| --- | --- | --- |
+| Installation, viewer workflows and Python API | [User guide](docs/en/README.md) | [使用手册](docs/zh/README.md) |
+| Algorithms, numerical conventions and implementation | [Implementation details](docs/en/development.md) | [开发细节](docs/zh/development.md) |
+
+## Contributing and support
+
+Report problems through [GitHub Issues](https://github.com/Yazhuo-Liu/DichromaticMap/issues)
+or [yliu3500@gatech.edu](mailto:yliu3500@gatech.edu). Contributions can be
+submitted as a pull request or by email; see the [contribution guide](CONTRIBUTING.md).
+This project is developed by volunteers and does not currently accept external
+donations.
+
+## License
+
+DichromaticMap is distributed under the [MIT License](LICENSE).