PyMieSimX 0.1.0__tar.gz → 0.1.1__tar.gz

{pymiesimx-0.1.0 → pymiesimx-0.1.1}/.github/workflows/quality.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.13"]
+        python-version: ["3.10", "3.11", "3.13"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

pymiesimx-0.1.1/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: PyMieSimX
+Version: 0.1.1
+Summary: Graphical Dash interface for PyMieSim.
+Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/MartinPdeS/PyMieSimX
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: PyMieSim<6,>=5.1.2
+Requires-Dist: dash<5,>=4.1.0
+Requires-Dist: gunicorn<24,>=23.0.0
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: plotly<7,>=5.24
+Requires-Dist: psycopg[binary]<4,>=3.2.9
+Provides-Extra: testing
+Requires-Dist: pytest>=8.0; extra == "testing"
+Requires-Dist: pytest-cov>=5.0; extra == "testing"
+Requires-Dist: coverage>=7.0; extra == "testing"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy==1.15.0; extra == "dev"
+Requires-Dist: ruff==0.11.2; extra == "dev"
+Dynamic: license-file
+
+PyMieSimX
+=========
+
+PyMieSimX is the standalone graphical interface for `PyMieSim
+<https://github.com/MartinPdeS/PyMieSim>`_. It provides a Dash application for
+configuring optical setups, running parameter sweeps, exploring individual
+particles, and exporting results.
+
+Source-model note
+-----------------
+
+The Gaussian source exposed by PyMieSimX is not a generalized Lorenz--Mie
+theory (GLMT) implementation. It is a convenience object for defining a
+Gaussian illumination through its numerical aperture and optical power in
+watts. The ``Gaussian`` and ``GaussianSet`` source options should therefore be
+interpreted as a practical source parameterization, not as a separate GLMT
+solver.
+
+Installation
+------------
+
+Install the GUI and its PyMieSim dependency with::
+
+    pip install PyMieSimX
+
+Launch the dashboard with::
+
+    pymiesimx
+
+Use ``pymiesimx --help`` to see the available host, port, browser, and debug
+options.
+
+Development
+-----------
+
+Install an editable checkout with::
+
+    pip install -e .
+
+The GUI source lives in ``PyMieSimX/gui``. Scientific calculations are provided
+by the installed ``PyMieSim`` package rather than duplicated here.
+
+Testing and automation
+----------------------
+
+Run the GUI test suite with::
+
+    pip install -e ".[testing]"
+    python -m pytest
+
+GitHub Actions includes quality checks, GUI tests, PyPI publishing, Conda
+recipe publishing, and coverage deployment. The Conda recipe is in
+``meta.yaml`` and the container entry point is defined in ``Dockerfile``.
+
+Python API
+----------
+
+The computational API can be used without constructing the Dash application::
+
+    from PyMieSimX import run_experiment
+
+    result = run_experiment(
+        source_type="GaussianSet",
+        source_values={
+            "wavelength": "650",
+            "polarization": "0",
+            "optical_power": "1e-3",
+            "numerical_aperture": "0.2",
+        },
+        scatterer_type="SphereSet",
+        scatterer_values={"diameter": "500", "material": "1.4", "medium": "1.0"},
+        detector_type="None",
+        detector_values={},
+        measure="Qsca",
+    )
+
+``PyMieSimX.create_dash_app`` and ``PyMieSimX.OpticalSetupGUI`` remain
+available for applications that need the graphical interface.
+
+Background calculations and limits
+-----------------------------------
+
+Parameter sweeps are submitted to a bounded background worker and reported to
+the dashboard through a polling status indicator. Results are guarded by both
+an in-memory dataframe limit and a serialized Dash-payload limit. Large-result
+warnings are logged before execution; oversized results are rejected with an
+actionable message asking you to reduce the sweep.
+
+Run the command-line launcher with ``--debug`` to enable detailed logs. Log
+messages use the format ``timestamp | level | logger | message`` and include
+experiment job identifiers, input configuration, queue transitions, dataframe
+memory usage, and serialized result sizes.
+
+Server-side usage metrics
+-------------------------
+
+The dashboard can share a PostgreSQL metrics database with RosettaX. Configure
+the Render service with::
+
+    PYMIESIMX_USAGE_METRICS_BACKEND=postgres
+    DATABASE_URL=<the shared PostgreSQL URL>
+
+PyMieSimX writes namespaced counters to the shared ``metrics_counters`` table:
+``pymiesimx_home_page_visit_count``, ``pymiesimx_experiment_run_count``, and
+``pymiesimx_single_run_count``. If PostgreSQL is unavailable, local development
+falls back to a JSON file under the platform's application-data directory.

pymiesimx-0.1.1/PyMieSimX/__init__.py

@@ -0,0 +1,58 @@
+"""Python API and optional Dash graphical interface for PyMieSim."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from PyMieSimX.api import (
+    MAX_SWEEP_COMBINATIONS,
+    MAX_RESULT_FRAME_BYTES,
+    MAX_RESULT_PAYLOAD_BYTES,
+    ExperimentValidationError,
+    ResultSizeEstimate,
+    ResultSizeLimitError,
+    ValidationIssue,
+    available_measures,
+    build_figure,
+    build_single_figure,
+    estimate_sweep_size,
+    export_result_to_csv,
+    export_single_result_to_csv,
+    estimate_result_size,
+    run_experiment,
+    validate_experiment_inputs,
+)
+
+try:
+    __version__ = version("PyMieSimX")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = [
+    "MAX_SWEEP_COMBINATIONS",
+    "MAX_RESULT_FRAME_BYTES",
+    "MAX_RESULT_PAYLOAD_BYTES",
+    "ExperimentValidationError",
+    "ResultSizeEstimate",
+    "ResultSizeLimitError",
+    "ValidationIssue",
+    "available_measures",
+    "build_figure",
+    "build_single_figure",
+    "estimate_sweep_size",
+    "export_result_to_csv",
+    "export_single_result_to_csv",
+    "estimate_result_size",
+    "run_experiment",
+    "validate_experiment_inputs",
+    "__version__",
+    "OpticalSetupGUI",
+    "create_dash_app",
+]
+
+
+def __getattr__(name: str):
+    """Load the optional Dash interface only when it is explicitly requested."""
+    if name in {"OpticalSetupGUI", "create_dash_app"}:
+        from PyMieSimX.gui.interface import OpticalSetupGUI, create_dash_app
+
+        return {"OpticalSetupGUI": OpticalSetupGUI, "create_dash_app": create_dash_app}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{pymiesimx-0.1.0 → pymiesimx-0.1.1}/PyMieSimX/__main__.py

@@ -2,8 +2,7 @@
 
 import argparse
 import logging
-
-from PyMieSimX.gui.interface import OpticalSetupGUI
+import sys
 
 
 def _build_argument_parser() -> argparse.ArgumentParser:
@@ -16,13 +15,25 @@ def _build_argument_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] | None = None) -> None:
-    """Launch the PyMieSimX dashboard from a console entry point."""
-    args = _build_argument_parser().parse_args(argv)
+def configure_logging(*, debug: bool, log_level: str = "INFO") -> int:
+    """Configure application logging using RosettaX's console format."""
+    resolved_level = logging.DEBUG if debug else getattr(logging, str(log_level).upper(), logging.INFO)
     logging.basicConfig(
-        level=logging.DEBUG if args.debug else logging.INFO,
+        level=resolved_level,
         format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        stream=sys.stdout,
+        force=True,
     )
+    logging.getLogger("PyMieSimX").setLevel(resolved_level)
+    return resolved_level
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Launch the PyMieSimX dashboard from a console entry point."""
+    args = _build_argument_parser().parse_args(argv)
+    configure_logging(debug=args.debug)
+    from PyMieSimX.gui.interface import OpticalSetupGUI
+
     OpticalSetupGUI().run(
         host=args.host,
         port=args.port,

pymiesimx-0.1.1/PyMieSimX/api.py

@@ -0,0 +1,39 @@
+"""Stable, GUI-independent Python API for PyMieSimX computations."""
+
+from PyMieSimX.gui.services import (
+    MAX_SWEEP_COMBINATIONS,
+    MAX_RESULT_FRAME_BYTES,
+    MAX_RESULT_PAYLOAD_BYTES,
+    ExperimentValidationError,
+    ResultSizeEstimate,
+    ResultSizeLimitError,
+    ValidationIssue,
+    available_measures,
+    build_figure,
+    build_single_figure,
+    estimate_sweep_size,
+    export_result_to_csv,
+    export_single_result_to_csv,
+    estimate_result_size,
+    run_experiment,
+    validate_experiment_inputs,
+)
+
+__all__ = [
+    "MAX_SWEEP_COMBINATIONS",
+    "MAX_RESULT_FRAME_BYTES",
+    "MAX_RESULT_PAYLOAD_BYTES",
+    "ExperimentValidationError",
+    "ResultSizeEstimate",
+    "ResultSizeLimitError",
+    "ValidationIssue",
+    "available_measures",
+    "build_figure",
+    "build_single_figure",
+    "estimate_sweep_size",
+    "export_result_to_csv",
+    "export_single_result_to_csv",
+    "estimate_result_size",
+    "run_experiment",
+    "validate_experiment_inputs",
+]

pymiesimx-0.1.1/PyMieSimX/application/__init__.py

@@ -0,0 +1 @@
+"""WSGI compatibility entry points for the PyMieSimX dashboard."""

pymiesimx-0.1.1/PyMieSimX/application/wsgi.py

@@ -0,0 +1,9 @@
+"""WSGI entry point for deployments using Gunicorn or another WSGI server."""
+
+from PyMieSimX.__main__ import configure_logging
+
+configure_logging(debug=False)
+
+from PyMieSimX.gui.interface import server  # noqa: E402
+
+__all__ = ["server"]

pymiesimx-0.1.1/PyMieSimX/gui/__init__.py

@@ -0,0 +1,12 @@
+"""Dash dashboard components for PyMieSimX."""
+
+__all__ = ["OpticalSetupGUI", "create_dash_app"]
+
+
+def __getattr__(name: str):
+    """Load the Dash application lazily for computational-only imports."""
+    if name in __all__:
+        from PyMieSimX.gui.interface import OpticalSetupGUI, create_dash_app
+
+        return {"OpticalSetupGUI": OpticalSetupGUI, "create_dash_app": create_dash_app}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{pymiesimx-0.1.0 → pymiesimx-0.1.1}/PyMieSimX/gui/assets/dashboard.css

@@ -208,7 +208,7 @@ body {
 .plot-options-grid {
     display: grid;
     grid-template-columns: repeat(8, minmax(104px, 1fr));
-    gap: 10px 12px;
+    gap: 6px 8px;
 }
 
 .plot-option-field {
@@ -806,6 +806,43 @@ html .rosettax-workflow-step-card--purple { border-left: 4px solid #8d6bd8 !impo
     line-height: 1.5;
 }
 
+.documentation-equation {
+    margin: 10px 0;
+    padding: 9px 12px;
+    border: 1px solid rgba(13, 110, 253, .16);
+    border-radius: 8px;
+    background: rgba(13, 110, 253, .05);
+    color: #204a74;
+    font-family: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    font-size: .84rem;
+    line-height: 1.45;
+    overflow-x: auto;
+}
+
+.documentation-table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 8px 0 4px;
+    font-size: .82rem;
+}
+
+.documentation-table th,
+.documentation-table td {
+    border: 1px solid rgba(13, 110, 253, .16);
+    padding: 7px 8px;
+    text-align: left;
+}
+
+.documentation-table th {
+    background: rgba(13, 110, 253, .08);
+    color: #204a74;
+    font-weight: 700;
+}
+
+.documentation-table td {
+    color: #52697a;
+}
+
 @media (max-width: 1000px) {
     .documentation-quickstart-body,
     .documentation-model-grid {
@@ -2429,6 +2466,80 @@ html .field-input {
     overflow-wrap: anywhere;
 }
 
+.material-field-controls {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 8px;
+    align-items: stretch;
+}
+
+.material-mode-toggle {
+    border: 1px solid var(--line);
+    background: var(--panel-strong);
+    border-radius: 999px;
+    padding: 4px 6px;
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    width: fit-content;
+    cursor: pointer;
+    margin-bottom: 8px;
+}
+
+.material-mode-label {
+    font-size: .84rem;
+    font-weight: 700;
+    line-height: 1;
+    color: var(--muted);
+    min-width: 56px;
+    text-align: center;
+}
+
+.material-mode-knob {
+    width: 26px;
+    height: 26px;
+    border-radius: 999px;
+    background: #d8e1e8;
+    transform: translateX(-5px);
+    transition: background .16s ease, transform .16s ease;
+}
+
+.material-mode-toggle.is-index .material-mode-label-ri {
+    color: #0d6efd;
+}
+
+.material-mode-toggle.is-material .material-mode-label-material {
+    color: #0d6efd;
+}
+
+.material-mode-toggle.is-material .material-mode-knob {
+    transform: translateX(5px);
+    background: #0d6efd;
+}
+
+.material-mode-toggle:focus-visible {
+    outline: 0;
+    border-color: rgba(44, 120, 180, 0.65);
+    box-shadow: 0 0 0 2px rgba(44, 120, 180, 0.18);
+}
+
+.material-name-select .Select-control {
+    min-height: 48px;
+    border-radius: 12px;
+}
+
+.material-name-select .Select-placeholder,
+.material-name-select .Select-value-label,
+.material-name-select .Select-input > input {
+    line-height: 46px;
+}
+
+@media (max-width: 760px) {
+    .material-mode-label {
+        min-width: 48px;
+    }
+}
+
 .dashboard-dropdown .Select-control,
 .dashboard-dropdown .Select-menu-outer,
 .dashboard-dropdown .Select-menu,

pymiesimx-0.1.1/PyMieSimX/gui/assets/materials-stock.json

@@ -0,0 +1,142 @@
+{
+  "materials": [
+    "fused_silica",
+    "BK7",
+    "water",
+    "air",
+    "polystyren",
+    "soda_lime_glass",
+    "crown",
+    "flint",
+    "BAK1",
+    "BAF10",
+    "gold",
+    "silver"
+  ],
+  "sellmeier_reference": [
+    {
+      "material": "fused_silica",
+      "formula": "Formula 1",
+      "B1": "0.6961663",
+      "B2": "0.4079426",
+      "B3": "0.8974794",
+      "C1_um2": "0.004679148",
+      "C2_um2": "0.013512063",
+      "C3_um2": "97.9340025"
+    },
+    {
+      "material": "BK7",
+      "formula": "Formula 2",
+      "B1": "1.18318503",
+      "B2": "0.0871756426",
+      "B3": "1.03133701",
+      "C1_um2": "0.00722141956",
+      "C2_um2": "0.0268216805",
+      "C3_um2": "101.702362"
+    },
+    {
+      "material": "water",
+      "formula": "Formula 2",
+      "B1": "0.5672526103",
+      "B2": "0.1736581125",
+      "B3": "0.02121531502",
+      "C1_um2": "0.005085550461",
+      "C2_um2": "0.01814938654",
+      "C3_um2": "0.02617260739"
+    },
+    {
+      "material": "air",
+      "formula": "Formula 6",
+      "B1": "0.05792105",
+      "B2": "0.00167917",
+      "B3": "—",
+      "C1_um2": "238.0185",
+      "C2_um2": "57.362",
+      "C3_um2": "—",
+      "parameters": "B1=0.05792105, C1=238.0185; B2=0.00167917, C2=57.362"
+    },
+    {
+      "material": "polystyren",
+      "formula": "Formula 2",
+      "B1": "1.4435",
+      "B2": "—",
+      "B3": "—",
+      "C1_um2": "0.020216",
+      "C2_um2": "—",
+      "C3_um2": "—"
+    },
+    {
+      "material": "soda_lime_glass",
+      "formula": "Formula 5",
+      "B1": "—",
+      "B2": "—",
+      "B3": "—",
+      "C1_um2": "—",
+      "C2_um2": "—",
+      "C3_um2": "—",
+      "parameters": "A=1.5130; B1=-0.003169, C1=2; B2=0.003962, C2=-2"
+    },
+    {
+      "material": "crown",
+      "formula": "Formula 2",
+      "B1": "1.1273555",
+      "B2": "0.124412303",
+      "B3": "0.827100531",
+      "C1_um2": "0.00720341707",
+      "C2_um2": "0.0269835916",
+      "C3_um2": "100.384588"
+    },
+    {
+      "material": "flint",
+      "formula": "Formula 2",
+      "B1": "1.34533359",
+      "B2": "0.209073176",
+      "B3": "0.937357162",
+      "C1_um2": "0.00997743871",
+      "C2_um2": "0.0470450767",
+      "C3_um2": "111.886764"
+    },
+    {
+      "material": "BAK1",
+      "formula": "Formula 2",
+      "B1": "1.12365662",
+      "B2": "0.309276848",
+      "B3": "0.881511957",
+      "C1_um2": "0.00644742752",
+      "C2_um2": "0.0222284402",
+      "C3_um2": "107.297751"
+    },
+    {
+      "material": "BAF10",
+      "formula": "Formula 2",
+      "B1": "1.5851495",
+      "B2": "0.143559385",
+      "B3": "1.08521269",
+      "C1_um2": "0.00926681282",
+      "C2_um2": "0.0424489805",
+      "C3_um2": "105.613573"
+    },
+    {
+      "material": "gold",
+      "formula": "Tabulated",
+      "B1": "—",
+      "B2": "—",
+      "B3": "—",
+      "C1_um2": "—",
+      "C2_um2": "—",
+      "C3_um2": "—",
+      "parameters": "Tabulated n(lambda) and k(lambda) data"
+    },
+    {
+      "material": "silver",
+      "formula": "Tabulated",
+      "B1": "—",
+      "B2": "—",
+      "B3": "—",
+      "C1_um2": "—",
+      "C2_um2": "—",
+      "C3_um2": "—",
+      "parameters": "Tabulated n(lambda) and k(lambda) data"
+    }
+  ]
+}

pymiesimx-0.1.1/PyMieSimX/gui/callback_helpers.py

@@ -0,0 +1,112 @@
+"""Pure orchestration helpers used by the Dash callbacks.
+
+Keeping state conversion and callback error handling here makes the expensive
+parts of the dashboard testable without invoking Dash's callback machinery.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from PyMieSimX.gui.services import ExperimentValidationError, build_single_figure, run_experiment
+
+
+@dataclass(frozen=True)
+class CallbackExecution:
+    """Serializable outcome of a computation requested by a Dash callback."""
+
+    result: dict[str, Any] | None
+    run_count: int
+    message: str
+    level: str
+
+
+def pair_ids_with_values(ids: list[dict[str, str]], values: list[str]) -> dict[str, str]:
+    """Convert dynamic Dash field IDs and values into a flat mapping."""
+    return {field_id["name"]: value for field_id, value in zip(ids, values)}
+
+
+def merge_local_plot_values(settings: dict | None, values: tuple[Any, ...]) -> dict:
+    """Overlay values from a plot-local options card onto stored preferences."""
+    merged = dict(settings or {})
+    names = ("x_scale", "log_y", "font_size", "line_width", "show_legend", "show_grid")
+    for name, value in zip(names, values):
+        if value is not None:
+            merged[name] = value
+    return merged
+
+
+def execute_experiment_callback(
+    *,
+    source_type: str,
+    source_values: list[str],
+    source_ids: list[dict[str, str]],
+    scatterer_type: str,
+    scatterer_values: list[str],
+    scatterer_ids: list[dict[str, str]],
+    detector_type: str,
+    detector_values: list[str],
+    detector_ids: list[dict[str, str]],
+    measure: str,
+    run_count: int | None,
+) -> CallbackExecution:
+    """Execute a parameter sweep and convert errors into UI-ready state."""
+    next_count = int(run_count or 0)
+    try:
+        result = run_experiment(
+            source_type=source_type,
+            source_values=pair_ids_with_values(source_ids, source_values),
+            scatterer_type=scatterer_type,
+            scatterer_values=pair_ids_with_values(scatterer_ids, scatterer_values),
+            detector_type=detector_type,
+            detector_values=pair_ids_with_values(detector_ids, detector_values),
+            measure=measure,
+        )
+    except ExperimentValidationError as error:
+        return CallbackExecution(None, next_count, " ".join(issue.message for issue in error.issues), "error")
+    except (TypeError, ValueError, KeyError) as error:
+        return CallbackExecution(None, next_count, str(error), "error")
+
+    return CallbackExecution(result, next_count + 1, f"Completed {result['row_count']:,} result rows.", "success")
+
+
+def execute_single_callback(
+    *,
+    source_type: str,
+    source_values: list[str],
+    source_ids: list[dict[str, str]],
+    scatterer_type: str,
+    scatterer_values: list[str],
+    scatterer_ids: list[dict[str, str]],
+    representation: str,
+    projection: str,
+    sampling: int,
+    nearfield_mode: list[str] | str | None,
+    include_incident_field: list[str] | None,
+    run_count: int | None,
+) -> CallbackExecution:
+    """Execute a particle representation and convert errors into UI state."""
+    next_count = int(run_count or 0)
+    nearfield_values = nearfield_mode if isinstance(nearfield_mode, list) else ([nearfield_mode] if nearfield_mode else [])
+    try:
+        figure, summary = build_single_figure(
+            source_type=source_type,
+            source_values=pair_ids_with_values(source_ids, source_values),
+            scatterer_type=scatterer_type,
+            scatterer_values=pair_ids_with_values(scatterer_ids, scatterer_values),
+            representation=representation,
+            projection=projection,
+            sampling=sampling or 120,
+            nearfield_mode="absolute" if "absolute" in nearfield_values else "real",
+            include_incident_field="include" in (include_incident_field or []),
+        )
+    except (TypeError, ValueError, KeyError) as error:
+        return CallbackExecution(None, next_count, str(error), "error")
+
+    return CallbackExecution(
+        {"figure": figure.to_plotly_json(), "summary": summary},
+        next_count + 1,
+        "Representation calculated.",
+        "success",
+    )