PyMieSimX 0.1.0__tar.gz → 0.1.3__tar.gz

{pymiesimx-0.1.0 → pymiesimx-0.1.3}/.coveragerc

@@ -8,6 +8,7 @@ omit =
     PyMieSimX/**/__main__.py
 
 [report]
+fail_under = 52
 skip_covered = True
 show_missing = True
 precision = 2

{pymiesimx-0.1.0 → pymiesimx-0.1.3}/.github/workflows/deploy_PyPi.yml

@@ -1,19 +1,17 @@
-name: Deploy to PyPI
+name: Publish to PyPI
 
 on:
   push:
-    branches: ["master"]
-    tags: ["*"]
-  pull_request:
-    branches: ["master"]
+    tags: ["v*"]
 
 permissions:
   contents: read
 
 jobs:
-  PyPI:
-    uses: MartinPdeS/MPSActions/.github/workflows/publish_pure_package_to_PyPi.yml@master
+  publish:
+    uses: MartinPdeS/MPSActions/.github/workflows/publish_pure_package_to_PyPi.yml@v5
     with:
       python-version: "3.11"
+      test-command: python -c 'import PyMieSimX'
     secrets:
       PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}

{pymiesimx-0.1.0 → pymiesimx-0.1.3}/.github/workflows/deploy_anaconda.yml

@@ -1,21 +1,20 @@
-name: Deploy Conda Packages
+name: Publish Conda package
 
 on:
   push:
-    branches: [ "master" ]
-    tags: '*'
-  pull_request:
-    branches: [ "master" ]
+    tags: ["v*"]
 
 permissions:
-    contents: write
+  contents: read
 
 jobs:
-  linux:
-    uses: MartinPdeS/MPSActions/.github/workflows/publish_compiled_package_to_anaconda.yml@master
+  publish:
+    uses: MartinPdeS/MPSActions/.github/workflows/publish_compiled_package_to_anaconda.yml@v5
     with:
       python_versions: '["3.11", "3.12", "3.13"]'
-      apt_package: ""
       os_list: '["ubuntu-latest", "macos-latest", "windows-latest"]'
+      package_name: pymiesimx
+      recipe_path: conda.recipe
+      test_import: PyMieSimX
     secrets:
       ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_API_TOKEN }}

{pymiesimx-0.1.0 → pymiesimx-0.1.3}/.github/workflows/deploy_coverage.yml

@@ -16,11 +16,11 @@ jobs:
     name: Run GUI tests and publish coverage
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
         with:
           python-version: "3.11"
 
@@ -29,6 +29,9 @@ jobs:
           python -m pip install --upgrade pip wheel build
           python -m pip install -e ".[testing]"
 
+      - name: Initialize material catalog
+        run: python -m PyOptik setup --no-progress
+
       - name: Run GUI tests with coverage
         run: |
           coverage erase

pymiesimx-0.1.3/.github/workflows/quality.yml

@@ -0,0 +1,47 @@
+name: Quality and GUI tests
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+permissions:
+  contents: read
+
+jobs:
+  python-quality:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and quality tools
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[testing,dev]"
+      - name: Initialize material catalog
+        run: python -m PyOptik setup --no-progress
+      - name: Ruff
+        run: python -m ruff check PyMieSimX tests
+      - name: Mypy
+        run: python -m mypy PyMieSimX/gui/parsing.py PyMieSimX/gui/schemas.py PyMieSimX/gui/models.py PyMieSimX/gui/jobs.py PyMieSimX/gui/callback_helpers.py PyMieSimX/gui/admin.py
+      - name: GUI tests
+        run: python -m pytest
+
+  browser-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: "3.11"
+      - name: Install package and browser test tools
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[testing,browser]"
+      - name: Initialize material catalog
+        run: python -m PyOptik setup --no-progress
+      - name: Browser workflow tests
+        # The full GUI suite enforces the repository-wide coverage threshold.
+        run: python -m pytest tests/browser --config-file=pytest.ini --headless --cov=PyMieSimX --cov-report=term --cov-fail-under=0

pymiesimx-0.1.3/.github/workflows/tests.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip && python -m pip install -e ".[testing]"
+      - run: python -m PyOptik setup --no-progress
+      - run: python -m pytest -q

{pymiesimx-0.1.0 → pymiesimx-0.1.3}/.gitignore

@@ -10,3 +10,10 @@ dist/
 .coverage
 htmlcov/
 .DS_Store
+!conda.recipe/
+!conda.recipe/meta.yaml
+!CONTRIBUTING.md
+!makefile
+!Makefile
+!tools/
+!tools/*.py

pymiesimx-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing to PyMieSimX
+
+Use Python 3.10 or newer. Install development dependencies with `python -m pip install -e ".[testing,dev]"`, then run `make quality` and `make test`.
+
+Releases use semantic version tags. Run `make patch`, `make minor`, or `make major` from a clean `master` checkout; the command creates the release commit, tags it, and pushes both. Publishing workflows run only for `v*` tags.
+
+The Conda recipe is at `conda.recipe/meta.yaml`. Do not commit build artefacts, virtual environments, or caches.

{pymiesimx-0.1.0 → pymiesimx-0.1.3}/Dockerfile

@@ -7,6 +7,7 @@ WORKDIR /app
 COPY . .
 
 RUN python -m pip install --upgrade pip \
-    && python -m pip install --no-cache-dir .
+    && python -m pip install --no-cache-dir . \
+    && python -m PyOptik setup --no-progress
 
 CMD ["sh", "-c", "exec gunicorn PyMieSimX.gui.interface:app --bind 0.0.0.0:${PORT:-8050} --workers 1 --threads 2 --timeout 3600"]

pymiesimx-0.1.3/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: PyMieSimX
+Version: 0.1.3
+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.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: PyMieSim<6,>=5.6.4
+Requires-Dist: PyOptik<4,>=3.2.1
+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: browser
+Requires-Dist: dash[testing]<5,>=4.1; extra == "browser"
+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 with PyMieSim and PyOptik with::
+
+    pip install PyMieSimX
+
+The first ``pymiesimx`` launch downloads PyOptik's complete
+RefractiveIndex.INFO snapshot. It can also be initialized explicitly with::
+
+    python -m PyOptik setup --no-progress
+
+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``. Metrics are collected only when the PostgreSQL
+backend is explicitly configured and available. Local installations do not
+persist usage counters.
+
+Administration page
+-------------------
+
+Usage counters are shown only on the hidden, token-protected administration
+page. Configure a server-side token with::
+
+    PYMIESIMX_ADMIN_TOKEN=<a long random value>
+
+Then open ``/admin?token=<the same value>``. The page is intentionally absent
+from the public sidebar and refreshes its counters every 30 seconds.

pymiesimx-0.1.3/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.3}/PyMieSimX/__main__.py

@@ -2,8 +2,10 @@
 
 import argparse
 import logging
+import sys
 
-from PyMieSimX.gui.interface import OpticalSetupGUI
+
+LOGGER = logging.getLogger(__name__)
 
 
 def _build_argument_parser() -> argparse.ArgumentParser:
@@ -16,13 +18,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.3/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.3/PyMieSimX/application/__init__.py

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

pymiesimx-0.1.3/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.3/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.3/PyMieSimX/gui/admin.py

@@ -0,0 +1,122 @@
+"""Token-gated administration dashboard for server-side usage counters."""
+
+import hmac
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from dash import dcc, html
+
+from PyMieSimX.gui import usage_metrics
+from PyMieSimX.gui.components import Card
+
+
+ADMIN_TOKEN_ENV_VAR = "PYMIESIMX_ADMIN_TOKEN"
+REFRESH_INTERVAL_MILLISECONDS = 30_000
+
+
+@dataclass(frozen=True)
+class AdminDashboardData:
+    """Snapshot displayed by the administration dashboard."""
+
+    metrics: usage_metrics.UsageMetrics = field(default_factory=usage_metrics.UsageMetrics)
+    generated_at: str = ""
+
+
+def is_admin_access_granted(provided_token: Any) -> bool:
+    """Return whether the provided token exactly matches server configuration."""
+    configured_token = os.getenv(ADMIN_TOKEN_ENV_VAR, "").strip()
+    candidate_token = str(provided_token or "").strip()
+    return bool(configured_token and candidate_token and hmac.compare_digest(configured_token, candidate_token))
+
+
+def collect_admin_dashboard_data() -> AdminDashboardData:
+    """Load the current server-side usage counters."""
+    return AdminDashboardData(
+        metrics=usage_metrics.load_usage_metrics(),
+        generated_at=f"{datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S')} UTC",
+    )
+
+
+def metric_text(value: object) -> str:
+    """Format a metric for display, including unavailable local values."""
+    if isinstance(value, float) and value != value:
+        return "NaN"
+    return str(value)
+
+
+def dashboard_values(data: AdminDashboardData) -> tuple[str, str, str, str]:
+    """Return callback-ready metric values and update timestamp."""
+    metrics = data.metrics
+    return (
+        metric_text(metrics.home_page_visit_count),
+        metric_text(metrics.experiment_run_count),
+        metric_text(metrics.single_run_count),
+        f"Last updated: {data.generated_at}",
+    )
+
+
+def build_admin_page(token: str | None) -> html.Div:
+    """Build the hidden dashboard or an intentionally generic denial page."""
+    if not is_admin_access_granted(token):
+        return html.Div(
+            html.Section(
+                className=Card.classes(color="blue", extra="admin-access-card"),
+                children=[
+                    html.H2("Page not available"),
+                    html.P("The requested page is not available on this server."),
+                ],
+            ),
+            className="page-content-stack admin-page",
+        )
+
+    values = dashboard_values(collect_admin_dashboard_data())
+    tiles = (
+        ("admin-home-page-visits", values[0], "Home page visits"),
+        ("admin-experiment-runs", values[1], "Parameter sweeps"),
+        ("admin-single-runs", values[2], "Particle explorations"),
+    )
+    return html.Div(
+        className="page-content-stack admin-page",
+        children=[
+            dcc.Interval(id="admin-refresh-interval", interval=REFRESH_INTERVAL_MILLISECONDS, n_intervals=0),
+            html.Section(
+                className="page-hero",
+                children=[
+                    html.H1("Administration"),
+                    html.P("Server-side PyMieSimX usage metrics.", className="hero-text"),
+                    html.Div(
+                        [
+                            html.Span(values[3], id="admin-last-updated"),
+                            html.Button("Refresh", id="admin-refresh-button", n_clicks=0, className="run-button"),
+                        ],
+                        className="admin-toolbar",
+                    ),
+                ],
+            ),
+            html.Div(
+                [
+                    html.Section(
+                        className=Card.classes(color="blue", extra="admin-metric-card"),
+                        children=[
+                            html.Div(value, id=value_id, className="admin-metric-value"),
+                            html.Div(label, className="admin-metric-label"),
+                        ],
+                    )
+                    for value_id, value, label in tiles
+                ],
+                className="admin-metric-grid",
+            ),
+        ],
+    )
+
+
+__all__ = [
+    "ADMIN_TOKEN_ENV_VAR",
+    "AdminDashboardData",
+    "build_admin_page",
+    "collect_admin_dashboard_data",
+    "dashboard_values",
+    "is_admin_access_granted",
+]