advisor-scattering 0.5.0__tar.gz

advisor_scattering-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include advisor/resources *

advisor_scattering-0.5.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: advisor-scattering
+Version: 0.5.0
+Summary: Advisor-Scattering: Advanced Visual Scattering Toolkit for Reciprocal-space
+Author: Xunyang Hong
+License: Proprietary
+Project-URL: Homepage, https://github.com/HongXunyang/advisor
+Project-URL: Documentation, https://advisor-scattering.readthedocs.io/en/latest/
+Keywords: scattering,reciprocal-space,pyqt,visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyQt5>=5.15.11
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: Dans_Diffraction>=3.3.3
+
+# Advisor-Scattering — Advanced Visual Scattering Toolkit for Reciprocal-space
+
+![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
+![PyQt5](https://img.shields.io/badge/PyQt5-5.15+-green.svg)
+
+Advisor-Scattering is a PyQt5 desktop app for X-ray scattering/diffraction experiments. It helps you convert scattering angles ↔ momentum transfer (HKL), explore scattering geometry, and visualize structure factors—all with interactive plots. Full docs on *[Read the Docs](https://advisor-scattering.readthedocs.io/en/latest/)*.
+
+![Demo video](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/showcase.gif)
+or use the link below to view the demo video.
+▶  [Demo video (MP4)](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/showcase.mp4)
+
+
+## Features
+- Convert scattering angles to momentum transfer (HKL) and vice versa.
+- Visualize scattering geometry and unit cells
+- Compute and visualize structure factors in reciprocal space.
+- CIF file drop-in support
+
+
+## Install
+- Python 3.8+ with PyQt5, numpy, scipy, matplotlib, Dans_Diffraction (see `requirements.txt`).
+
+From PyPI:
+```bash
+pip install advisor-scattering
+```
+
+From source:
+```bash
+python -m venv .venv
+source .venv/bin/activate  # .venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install .
+```
+
+## Run
+```bash
+advisor-scattering
+# or
+advisor
+# or
+python -m advisor
+```
+
+*Note: the install command is `pip install advisor-scattering`, and the import is `import advisor`*.
+
+------
+
+## Minimal workflow (60 seconds)
+1) Launch the app.  
+2) Enter lattice constants/angles and beam energy, or drop a CIF file.  
+3) Click **Initialize**.  
+4) Use the feature tabs (Scattering Geometry / Structure Factor) to calculate and visualize.
+
+![Init flow](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/init.gif)
+
+----
+
+## Using the app
+
+### 1. Initialization window
+- Enter lattice constants (a, b, c) and angles (alpha, beta, gamma); beam energy auto-updates wavelength/|k|.
+- Optional: drop a CIF to autofill lattice parameters and preview the unit cell.
+- Adjust Euler angles (roll, pitch, yaw) to orient the sample relative to the scattering plane;
+- Click **Initialize** to load the main interface and pass parameters to all tabs.
+
+### 2. Scattering Geometry tab
+- Angles → HKL: enter 2θ/θ/χ/φ, compute HKL.
+- HKL → Angles: enter HKL, compute feasible angles.
+- HK to Angles (fixed 2θ) and HKL scan (fixed 2θ) subtabs for trajectory planning.
+
+![Scattering geometry demo](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/scattering_geometry_tab_demo.gif)
+
+### 3. Structure Factor tab
+- Requires a CIF (from init) and an energy in the tab.
+- HKL plane: explore a 3D HKL cube with linked HK/HL/KL slices.
+- Customized plane: choose U/V vectors and a center to sample an arbitrary plane in reciprocal space.
+
+![Structure factor demo](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/structure_factor_tab_demo.gif)
+
+### 4. Resetting
+Use the toolbar button or **File → Reset Parameters** to return to the init window, clear the CIF lock, and re-enter parameters.
+
+------
+
+## Project structure (at a glance)
+```
+advisor/          application package
+  app.py          bootstrap
+  controllers/    app/feature coordinators
+  domain/         math and geometry helpers (no PyQt)
+  features/       per-feature domain/controller/ui code
+  ui/             shared UI pieces (init window, main window, base tab, visualizers)
+  resources/      QSS, icons, config JSON, sample data
+docs/             Sphinx sources and assets
+```
+
+## Documentation
+- Full Sphinx docs live in `docs/` and on *[Read the Docs](https://advisor-scattering.readthedocs.io/en/latest/)*.
+- Appendix covers scattering angle definitions and HKL conventions.

advisor_scattering-0.5.0/README.md

@@ -0,0 +1,100 @@
+# Advisor-Scattering — Advanced Visual Scattering Toolkit for Reciprocal-space
+
+![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
+![PyQt5](https://img.shields.io/badge/PyQt5-5.15+-green.svg)
+
+Advisor-Scattering is a PyQt5 desktop app for X-ray scattering/diffraction experiments. It helps you convert scattering angles ↔ momentum transfer (HKL), explore scattering geometry, and visualize structure factors—all with interactive plots. Full docs on *[Read the Docs](https://advisor-scattering.readthedocs.io/en/latest/)*.
+
+![Demo video](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/showcase.gif)
+or use the link below to view the demo video.
+▶  [Demo video (MP4)](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/showcase.mp4)
+
+
+## Features
+- Convert scattering angles to momentum transfer (HKL) and vice versa.
+- Visualize scattering geometry and unit cells
+- Compute and visualize structure factors in reciprocal space.
+- CIF file drop-in support
+
+
+## Install
+- Python 3.8+ with PyQt5, numpy, scipy, matplotlib, Dans_Diffraction (see `requirements.txt`).
+
+From PyPI:
+```bash
+pip install advisor-scattering
+```
+
+From source:
+```bash
+python -m venv .venv
+source .venv/bin/activate  # .venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install .
+```
+
+## Run
+```bash
+advisor-scattering
+# or
+advisor
+# or
+python -m advisor
+```
+
+*Note: the install command is `pip install advisor-scattering`, and the import is `import advisor`*.
+
+------
+
+## Minimal workflow (60 seconds)
+1) Launch the app.  
+2) Enter lattice constants/angles and beam energy, or drop a CIF file.  
+3) Click **Initialize**.  
+4) Use the feature tabs (Scattering Geometry / Structure Factor) to calculate and visualize.
+
+![Init flow](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/init.gif)
+
+----
+
+## Using the app
+
+### 1. Initialization window
+- Enter lattice constants (a, b, c) and angles (alpha, beta, gamma); beam energy auto-updates wavelength/|k|.
+- Optional: drop a CIF to autofill lattice parameters and preview the unit cell.
+- Adjust Euler angles (roll, pitch, yaw) to orient the sample relative to the scattering plane;
+- Click **Initialize** to load the main interface and pass parameters to all tabs.
+
+### 2. Scattering Geometry tab
+- Angles → HKL: enter 2θ/θ/χ/φ, compute HKL.
+- HKL → Angles: enter HKL, compute feasible angles.
+- HK to Angles (fixed 2θ) and HKL scan (fixed 2θ) subtabs for trajectory planning.
+
+![Scattering geometry demo](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/scattering_geometry_tab_demo.gif)
+
+### 3. Structure Factor tab
+- Requires a CIF (from init) and an energy in the tab.
+- HKL plane: explore a 3D HKL cube with linked HK/HL/KL slices.
+- Customized plane: choose U/V vectors and a center to sample an arbitrary plane in reciprocal space.
+
+![Structure factor demo](https://raw.githubusercontent.com/HongXunyang/advisor/main/docs/source/_static/structure_factor_tab_demo.gif)
+
+### 4. Resetting
+Use the toolbar button or **File → Reset Parameters** to return to the init window, clear the CIF lock, and re-enter parameters.
+
+------
+
+## Project structure (at a glance)
+```
+advisor/          application package
+  app.py          bootstrap
+  controllers/    app/feature coordinators
+  domain/         math and geometry helpers (no PyQt)
+  features/       per-feature domain/controller/ui code
+  ui/             shared UI pieces (init window, main window, base tab, visualizers)
+  resources/      QSS, icons, config JSON, sample data
+docs/             Sphinx sources and assets
+```
+
+## Documentation
+- Full Sphinx docs live in `docs/` and on *[Read the Docs](https://advisor-scattering.readthedocs.io/en/latest/)*.
+- Appendix covers scattering angle definitions and HKL conventions.

advisor_scattering-0.5.0/advisor/__init__.py

@@ -0,0 +1,3 @@
+"""Advisor-Scattering: Advanced Visual Scattering Toolkit for Reciprocal-space."""
+
+__all__ = ["main"]

advisor_scattering-0.5.0/advisor/__main__.py

@@ -0,0 +1,7 @@
+"""Entrypoint for running Advisor-Scattering as a module."""
+
+from .app import main
+
+
+if __name__ == "__main__":
+    main()

advisor_scattering-0.5.0/advisor/app.py

@@ -0,0 +1,40 @@
+"""Application bootstrap for Advisor-Scattering (Advanced Visual Scattering Toolkit for Reciprocal-space)."""
+
+import os
+import sys
+from PyQt5.QtWidgets import QApplication
+from PyQt5.QtCore import Qt, QLocale, QFile, QIODevice
+
+from advisor.controllers import AppController
+from advisor.resources import resources_rc
+
+
+def load_stylesheet() -> str:
+    """Load QSS stylesheet if present."""
+    base_dir = os.path.dirname(os.path.abspath(__file__))
+    qss_path = os.path.join(base_dir, "resources", "qss", "styles.qss")
+    if os.path.exists(qss_path):
+        with open(qss_path, "r", encoding="utf-8") as handle:
+            return handle.read()
+    return ""
+
+
+def main():
+    """Main application entry point."""
+    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True)
+    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)
+
+    app = QApplication(sys.argv)
+    app.setApplicationName("Advisor-Scattering")
+    QLocale.setDefault(QLocale(QLocale.English, QLocale.UnitedStates))
+    app.setStyleSheet(load_stylesheet())
+
+
+    controller = AppController(app)
+    controller.show()
+
+    sys.exit(app.exec_())
+
+
+if __name__ == "__main__":
+    main()

advisor_scattering-0.5.0/advisor/controllers/__init__.py

@@ -0,0 +1,6 @@
+"""Controllers coordinating views and domain logic."""
+
+from .feature_controller import FeatureController
+from .app_controller import AppController
+
+__all__ = ["AppController", "FeatureController"]

advisor_scattering-0.5.0/advisor/controllers/app_controller.py

@@ -0,0 +1,69 @@
+"""Top-level application controller."""
+
+import json
+import os
+from typing import Optional
+
+from PyQt5.QtWidgets import QApplication
+
+from advisor.features import ScatteringGeometryController, StructureFactorController
+from advisor.ui.init_window import InitWindow
+from advisor.ui.main_window import MainWindow
+
+
+class AppController:
+    """Coordinates application startup and feature wiring."""
+
+    def __init__(self, qt_app: QApplication):
+        self.app = qt_app
+        self.config = self._load_config()
+        self.parameters: Optional[dict] = None
+
+        self.main_window = MainWindow(controller=self)
+        self.init_window = InitWindow(controller=self)
+        self.main_window.attach_init_view(self.init_window)
+
+        self.features = [
+            ScatteringGeometryController(self),
+            StructureFactorController(self),
+        ]
+        for feature in self.features:
+            self.main_window.add_feature_tab(
+                feature.view, feature.title, feature.icon, feature.description
+            )
+
+        self.init_window.initialized.connect(self.apply_parameters)
+
+    def show(self):
+        """Show the main window."""
+        self.main_window.show()
+
+    def apply_parameters(self, params: dict):
+        """Store and propagate global parameters, then show tabs."""
+        self.parameters = params
+        for feature in self.features:
+            feature.set_parameters(params)
+        self.main_window.show_tabs()
+
+    def reset_parameters(self):
+        """Reset parameters and return to init view."""
+        self.parameters = None
+        if hasattr(self.init_window, "reset_inputs"):
+            self.init_window.reset_inputs()
+        self.main_window.show_init()
+
+    def get_parameters(self) -> dict:
+        """Return the current global parameters."""
+        return self.parameters or {}
+
+    def _load_config(self) -> dict:
+        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        config_path = os.path.join(base_dir, "resources", "config", "app_config.json")
+        try:
+            with open(config_path, "r", encoding="utf-8") as handle:
+                return json.load(handle)
+        except Exception:
+            return {
+                "app_name": "Advisor-Scattering",
+                "window_size": {"width": 1200, "height": 800},
+            }

advisor_scattering-0.5.0/advisor/controllers/feature_controller.py

@@ -0,0 +1,25 @@
+"""Base feature controller."""
+
+from typing import Optional
+from PyQt5.QtWidgets import QWidget
+
+
+class FeatureController:
+    """Base class for feature controllers."""
+
+    title: str = "Feature"
+    description: str = ""
+    icon: Optional[str] = None
+
+    def __init__(self, app_controller):
+        self.app_controller = app_controller
+        self.view: Optional[QWidget] = None
+
+    def set_parameters(self, params: dict):
+        """Propagate global parameters to the feature."""
+        raise NotImplementedError
+
+    def build_view(self) -> QWidget:
+        """Create and return the tab widget."""
+        raise NotImplementedError
+

advisor_scattering-0.5.0/advisor/domain/__init__.py

@@ -0,0 +1,23 @@
+"""Domain layer with calculation and model logic."""
+
+from .geometry import (
+    get_real_space_vectors,
+    get_reciprocal_space_vectors,
+    euler_to_matrix,
+    angle_to_matrix,
+    get_rotation,
+    sample_to_lab_conversion,
+    lab_to_sample_conversion,
+)
+from .unit_converter import UnitConverter
+
+__all__ = [
+    "get_real_space_vectors",
+    "get_reciprocal_space_vectors",
+    "euler_to_matrix",
+    "angle_to_matrix",
+    "get_rotation",
+    "sample_to_lab_conversion",
+    "lab_to_sample_conversion",
+    "UnitConverter",
+]

advisor_scattering-0.5.0/advisor/domain/core/__init__.py

@@ -0,0 +1,8 @@
+"""Core structural classes (Lattice, Sample, Lab)."""
+
+from .lattice import Lattice
+from .sample import Sample
+from .lab import Lab
+
+__all__ = ["Lattice", "Sample", "Lab"]
+

advisor_scattering-0.5.0/advisor/domain/core/lab.py

@@ -0,0 +1,121 @@
+"""This is a class for the lab."""
+
+import numpy as np
+
+from advisor.domain import angle_to_matrix
+from .sample import Sample
+
+
+
+class Lab:
+    """This is a class for the lab."""
+
+    def __init__(self):
+        """Initialize the lab."""
+        self.sample = Sample()
+
+        self.theta = 0
+        self.phi = 0
+        self.chi = 0
+        self.a_vec_lab = None
+        self.b_vec_lab = None
+        self.c_vec_lab = None
+        self.a_star_vec_lab = None
+        self.b_star_vec_lab = None
+        self.c_star_vec_lab = None
+
+    def initialize(
+        self, a, b, c, alpha, beta, gamma, roll, pitch, yaw, theta, phi, chi
+    ):
+        """Initialize the lab."""
+        self.sample.initialize(a, b, c, alpha, beta, gamma, roll, pitch, yaw)
+        self.theta = theta
+        self.phi = phi
+        self.chi = chi
+        self.calculate_real_space_vectors()
+        self.calculate_reciprocal_space_vectors()
+
+    def get_sample_angles(self):
+        """Get the sample angles."""
+        return self.theta, self.phi, self.chi
+
+    def get_lattice_angles(self):
+        """get the lattice euler angles: roll pitch and yaw"""
+        return self.sample.get_lattice_angles()
+
+    def get_lattice_parameters(self):
+        """Get the parameters of the sample."""
+        return self.sample.get_lattice_parameters()
+
+    def get_real_space_vectors(self, is_normalized=False):
+        """Get the real space vectors in the lab frame."""
+        if is_normalized:
+            return self.a_vec_lab / np.linalg.norm(self.a_vec_lab), self.b_vec_lab / np.linalg.norm(self.b_vec_lab), self.c_vec_lab / np.linalg.norm(self.c_vec_lab)
+        return self.a_vec_lab, self.b_vec_lab, self.c_vec_lab
+
+    def get_reciprocal_space_vectors(self, is_normalized=False):
+        """Get the reciprocal space vectors in the lab frame."""
+        if is_normalized:
+            return self.a_star_vec_lab / np.linalg.norm(self.a_star_vec_lab), self.b_star_vec_lab / np.linalg.norm(self.b_star_vec_lab), self.c_star_vec_lab / np.linalg.norm(self.c_star_vec_lab)
+        return self.a_star_vec_lab, self.b_star_vec_lab, self.c_star_vec_lab
+
+    def calculate_real_space_vectors(self):
+        """Get the real space vectors in the lab frame."""
+        a_vec_sample, b_vec_sample, c_vec_sample = self.sample.get_real_space_vectors()
+        rotation_matrix = angle_to_matrix(self.theta, self.phi, self.chi)
+        self.a_vec_lab = rotation_matrix @ a_vec_sample
+        self.b_vec_lab = rotation_matrix @ b_vec_sample
+        self.c_vec_lab = rotation_matrix @ c_vec_sample
+
+    def calculate_reciprocal_space_vectors(self):
+        """Get the reciprocal space vectors in the lab frame."""
+        a_star_vec_sample, b_star_vec_sample, c_star_vec_sample = (
+            self.sample.get_reciprocal_space_vectors()
+        )
+        rotation_matrix = angle_to_matrix(self.theta, self.phi, self.chi)
+        self.a_star_vec_lab = rotation_matrix @ a_star_vec_sample
+        self.b_star_vec_lab = rotation_matrix @ b_star_vec_sample
+        self.c_star_vec_lab = rotation_matrix @ c_star_vec_sample
+
+    def get_lab_basis(self):
+        """Get the lab orthogonal basis vectors, in the lab frame."""
+        ex_lab = np.array([1, 0, 0])
+        ey_lab = np.array([0, 1, 0])
+        ez_lab = np.array([0, 0, 1])
+        return ex_lab, ey_lab, ez_lab
+
+    def get_sample_basis(self):
+        """Get the sample orthogonal basis vectors, in the lab frame."""
+        ex_sample_in_sample, ey_sample_in_sample, ez_sample_in_sample = (
+            self.sample.get_sample_basis()
+        )  # sample basis in the sample frame
+
+        rotation_matrix = angle_to_matrix(self.theta, self.phi, self.chi)
+
+        # sample basis in the lab frame
+        ex_sample_in_lab = rotation_matrix @ ex_sample_in_sample
+        ey_sample_in_lab = rotation_matrix @ ey_sample_in_sample
+        ez_sample_in_lab = rotation_matrix @ ez_sample_in_sample
+        return ex_sample_in_lab, ey_sample_in_lab, ez_sample_in_lab
+
+    def get_lattice_basis(self):
+        """Get the lattice orthogonal basis vectors, in the lab frame."""
+        ex_lattice_in_sample, ey_lattice_in_sample, ez_lattice_in_sample = (
+            self.sample.get_lattice_basis()
+        )  # lattice basis in the sample frame
+
+        rotation_matrix = angle_to_matrix(self.theta, self.phi, self.chi)
+
+        # lattice basis in the lab frame
+        ex_lattice_in_lab = rotation_matrix @ ex_lattice_in_sample
+        ey_lattice_in_lab = rotation_matrix @ ey_lattice_in_sample
+        ez_lattice_in_lab = rotation_matrix @ ez_lattice_in_sample
+        return ex_lattice_in_lab, ey_lattice_in_lab, ez_lattice_in_lab
+
+    def rotate(self, theta, phi, chi):
+        """Rotate the lab."""
+        self.theta = theta
+        self.phi = phi
+        self.chi = chi
+        self.calculate_real_space_vectors()
+        self.calculate_reciprocal_space_vectors()

advisor_scattering-0.5.0/advisor/domain/core/lattice.py

@@ -0,0 +1,79 @@
+"""This is a module for the lattice class."""
+
+import numpy as np
+
+from advisor.domain import (
+    get_real_space_vectors,
+    get_reciprocal_space_vectors,
+)
+
+
+class Lattice:
+    """This is a class for the lattice."""
+
+    def __init__(self):
+        """Initialize the sample."""
+        self.a = None
+        self.b = None
+        self.c = None
+        self.alpha = None
+        self.beta = None
+        self.gamma = None
+
+        # vectors in the lattice frame
+        self.a_vec_lattice = None
+        self.b_vec_lattice = None
+        self.c_vec_lattice = None
+
+        # reciprocal vectors in the lattice frame
+        self.a_star_vec_lattice = None
+        self.b_star_vec_lattice = None
+        self.c_star_vec_lattice = None
+
+    def initialize(self, a, b, c, alpha, beta, gamma):
+        """Initialize the sample.
+
+        Args:
+            a, b, c (float): Lattice constants in Angstroms
+            alpha, beta, gamma (float): Lattice angles in degrees
+            roll, pitch, yaw (float): Euler angles in degrees
+        """
+        # First set the lattice parameters
+        self.a = a
+        self.b = b
+        self.c = c
+        self.alpha = alpha
+        self.beta = beta
+        self.gamma = gamma
+
+        # Then calculate vectors in sample coordinate system
+        self.a_vec_lattice, self.b_vec_lattice, self.c_vec_lattice = (
+            get_real_space_vectors(a, b, c, alpha, beta, gamma)
+        )
+        self.a_star_vec_lattice, self.b_star_vec_lattice, self.c_star_vec_lattice = (
+            get_reciprocal_space_vectors(a, b, c, alpha, beta, gamma)
+        )
+
+    def get_lattice_parameters(self):
+        """Get the parameters of the sample. if None, raise "initialize the sample first"."""
+        try:
+            a, b, c = self.a, self.b, self.c
+            alpha, beta, gamma = self.alpha, self.beta, self.gamma
+            return a, b, c, alpha, beta, gamma
+        except KeyError as exc:
+            raise ValueError("initialize the sample first") from exc
+
+    def get_real_space_vectors(self):
+        """Get the real space vectors in the lattice frame."""
+        return self.a_vec_lattice, self.b_vec_lattice, self.c_vec_lattice
+
+    def get_reciprocal_space_vectors(self):
+        """Get the reciprocal space vectors in the lattice frame."""
+        return self.a_star_vec_lattice, self.b_star_vec_lattice, self.c_star_vec_lattice
+
+    def get_lattice_basis(self):
+        """Get the lattice orthogonal basis vectors, in the lattice frame."""
+        ex_lattice_in_lattice = np.array([1, 0, 0])
+        ey_lattice_in_lattice = np.array([0, 1, 0])
+        ez_lattice_in_lattice = np.array([0, 0, 1])
+        return ex_lattice_in_lattice, ey_lattice_in_lattice, ez_lattice_in_lattice