PyMieSimX 0.1.0__py3-none-any.whl

PyMieSimX/gui/pages/home.py

@@ -0,0 +1,152 @@
+"""Home page composition."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from dash import html
+
+from PyMieSimX.gui.components import Card
+
+def build_home_page(metrics: dict[str, int] | None = None):
+    """Build the landing page and its workflow cards."""
+    metrics = metrics or {}
+    return html.Div(
+        className="page-content-stack",
+        children=[
+            html.Div(
+                [
+                    html.Span("Version:", className="version-widget-label"),
+                    html.Span(_package_version(), className="version-widget-value"),
+                ],
+                className="version-widget",
+            ),
+            html.Section(
+                className="page-hero home-page-hero",
+                children=[
+                    html.H1("PyMieSim"),
+                    html.P(
+                        "An open-source library for fast and flexible far-field Mie scattering simulations.",
+                        className="hero-text",
+                    ),
+                ],
+            ),
+            _citation_card(),
+            html.Div(
+                className="home-capability-grid",
+                children=[
+                    _capability_card(
+                        "Particle Explorer",
+                        "Inspect one optical setup through angular scattering, polarization, phase functions, and field representations.",
+                        ["Configure source", "Configure scatterer", "Render representations"],
+                        "Open Particle Explorer",
+                        "/single",
+                    ),
+                    _capability_card(
+                        "Parameter Sweep",
+                        "Run source, scatterer, and detector sets across parameter sweeps and export structured results for analysis.",
+                        ["Configure source", "Configure scatterer and detector", "Run and export results"],
+                        "Open Parameter Sweep",
+                        "/experiment",
+                    ),
+                    _capability_card(
+                        "Documentation",
+                        "Learn the PyMieSimX vocabulary, field syntax, supported objects, and recommended workflows.",
+                        ["Learn the model vocabulary", "Explore field syntax", "Follow recommended workflows"],
+                        "Read documentation",
+                        "/documentation",
+                    ),
+                ],
+            ),
+            _metrics_card(metrics),
+        ],
+    )
+
+
+def _package_version() -> str:
+    try:
+        return version("PyMieSim")
+    except PackageNotFoundError:
+        return "development"
+
+
+def _citation_card():
+    """Build the support and citation panel shown on the landing page."""
+    return html.Section(
+        className=Card.classes(color="blue", extra="home-info-card"),
+        children=[
+            html.Div("Support, citation, and lab", className="home-section-header"),
+            html.Div(
+                className="home-info-body",
+                children=[
+                    html.P(
+                        "Support PyMieSim development, cite the underlying work in publications, and learn more about the project.",
+                        className="home-info-copy",
+                    ),
+                    html.Div(
+                        className="home-button-row",
+                        children=[
+                            html.A("Support Developer", href="https://github.com/sponsors/MartinPdeS", target="_blank", rel="noopener noreferrer", className="home-button home-button-primary"),
+                            html.A("Citing this work", href="/citation", className="home-button home-button-outline"),
+                            html.A("PyMieSim documentation", href="https://martinpdes.github.io/PyMieSim/", target="_blank", rel="noopener noreferrer", className="home-button home-button-info"),
+                            html.A("GitHub repository", href="https://github.com/MartinPdeS/PyMieSim", target="_blank", rel="noopener noreferrer", className="home-button home-button-muted"),
+                            html.A("Install locally (Releases)", href="/documentation/install-local", className="home-button home-button-muted"),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+
+def _capability_card(title: str, description: str, steps: list[str], button_text: str, href: str):
+    return html.Section(
+        className=Card.classes(color="blue", extra="home-capability-card"),
+        children=[
+            html.Div(title, className="home-section-header"),
+            html.Div(
+                className="home-capability-body",
+                children=[
+                    html.P(description),
+                    html.Div(
+                        [html.Div([html.Span(str(index), className="home-step-number"), html.Span(step)]) for index, step in enumerate(steps, start=1)],
+                        className="home-step-list",
+                    ),
+                    html.A(button_text, href=href, className="home-workflow-button"),
+                ],
+            ),
+        ],
+    )
+
+
+def _metrics_card(metrics: dict[str, int]):
+    return html.Section(
+        className=Card.classes(color="blue", extra="home-info-card home-metrics-card"),
+        children=[
+            html.Div(className="card-header panel-header", children=[html.Div("PyMieSim usage metrics.", className="card-title")]),
+            html.Div(
+                className="card-body",
+                children=[
+                    html.Div(
+                        [
+                            html.Div(str(metrics.get("home_page_visits", 0)), className="home-metric-value"),
+                            html.Div("Home page visits", className="home-metric-label"),
+                        ],
+                        className="home-metric-tile",
+                    ),
+                    html.Div(
+                        [
+                            html.Div(str(metrics.get("experiment_runs", 0)), className="home-metric-value"),
+                            html.Div("Parameter sweeps", className="home-metric-label"),
+                        ],
+                        className="home-metric-tile",
+                    ),
+                    html.Div(
+                        [
+                            html.Div(str(metrics.get("single_runs", 0)), className="home-metric-value"),
+                            html.Div("Particle explorations", className="home-metric-label"),
+                        ],
+                        className="home-metric-tile",
+                    ),
+                ],
+            ),
+        ],
+    )

PyMieSimX/gui/pages/install_local.py

@@ -0,0 +1,110 @@
+"""Local installation documentation page."""
+
+from dash import html
+
+from PyMieSimX.gui.components import Card
+
+
+RELEASES_URL = "https://github.com/MartinPdeS/PyMieSim/releases"
+
+
+def _documentation_card(title: str, subtitle: str, body):
+    """Build a RosettaX-style documentation card."""
+    return html.Section(
+        className=Card.classes(color="blue", extra="panel documentation-card"),
+        children=[
+            html.Div(
+                className="card-header panel-header",
+                children=[
+                    html.Div(title, className="card-title"),
+                    html.Div(subtitle, className="card-subtitle"),
+                ],
+            ),
+            html.Div(className="card-body", children=body),
+        ],
+    )
+
+
+def _link_chip(label: str, href: str):
+    return html.A(label, href=href, className="documentation-link-chip")
+
+
+def build_install_local_page():
+    """Build the local-installation page linked from the home card."""
+    return html.Div(
+        className="page-content-stack",
+        children=[
+            html.Section(
+                className="page-hero documentation-page-hero",
+                children=[
+                    html.P("PyMieSim reference", className="eyebrow"),
+                    html.H1("Install PyMieSim Locally"),
+                    html.P(
+                        "This page explains how to download and run PyMieSim from its release distribution without building from source.",
+                        className="hero-text",
+                    ),
+                ],
+            ),
+            _documentation_card(
+                "Related pages",
+                "Use the documentation hub for workflow and model details after installation.",
+                [
+                    html.Div(
+                        [_link_chip("Back to documentation hub", "/documentation"), _link_chip("Quick start", "/documentation")],
+                        className="documentation-link-chips",
+                    )
+                ],
+            ),
+            html.Div(
+                className="install-local-grid",
+                children=[
+                    _documentation_card(
+                        "Download latest release bundle",
+                        "Choose the archive for your operating system.",
+                        [
+                            html.Div(
+                                [
+                                    html.A("Download Windows", href=RELEASES_URL, target="_blank", rel="noopener noreferrer", className="install-download-button"),
+                                    html.A("Download macOS", href=RELEASES_URL, target="_blank", rel="noopener noreferrer", className="install-download-button"),
+                                    html.A("Download Linux", href=RELEASES_URL, target="_blank", rel="noopener noreferrer", className="install-download-button"),
+                                ],
+                                className="install-download-buttons",
+                            ),
+                            html.Div(
+                                [
+                                    "Need a different version? Use the full ",
+                                    html.A("Releases page", href=RELEASES_URL, target="_blank", rel="noopener noreferrer"),
+                                    ".",
+                                ],
+                                className="install-release-note",
+                            ),
+                        ],
+                    ),
+                    _documentation_card(
+                        "Install and run",
+                        "Run PyMieSim after installing the package.",
+                        [
+                            html.Ol(
+                                [
+                                    html.Li("Download the archive for your operating system."),
+                                    html.Li("Extract it to a folder where you have write permission."),
+                                    html.Li("Install PyMieSim in your Python environment."),
+                                    html.Li("Launch the PyMieSim GUI and open the local dashboard."),
+                                ],
+                                className="install-steps",
+                            )
+                        ],
+                    ),
+                ],
+            ),
+            _documentation_card(
+                "Validation and provenance",
+                "Recommended checks before using a local installation.",
+                [
+                    html.Div("Confirm you downloaded the expected version from the release page."),
+                    html.Div("Keep the installed version together with reports for traceability."),
+                    html.Div("For source-based installation, follow the instructions in the main documentation."),
+                ],
+            ),
+        ],
+    )

PyMieSimX/gui/pages/settings.py

@@ -0,0 +1,87 @@
+"""Settings page composition and independent plotting preferences."""
+
+from __future__ import annotations
+
+from dash import dcc, html
+
+from PyMieSimX.gui.components import Card
+from PyMieSimX.gui.defaults import DEFAULT_APPLICATION_SETTINGS, DEFAULT_PARTICLE_PLOT_SETTINGS, DEFAULT_SWEEP_PLOT_SETTINGS
+
+
+def build_settings_page(theme: str = DEFAULT_APPLICATION_SETTINGS["theme"], plot_settings: dict | None = None):
+    """Build the settings page with separate controls for each workspace."""
+    stored = plot_settings or {}
+    particle = _workspace_settings(stored, "particle_explorer", DEFAULT_PARTICLE_PLOT_SETTINGS)
+    sweep = _workspace_settings(stored, "parameter_sweep", DEFAULT_SWEEP_PLOT_SETTINGS)
+    return html.Div(
+        className="page-content-stack settings-page",
+        children=[
+            html.Section(
+                className="page-hero documentation-page-hero",
+                children=[
+                    html.P("Application preferences", className="eyebrow"),
+                    html.H1("Settings"),
+                    html.P("Tune the dashboard appearance and configure each plotting workspace independently. Changes are saved automatically in this browser.", className="hero-text"),
+                ],
+            ),
+            html.Div(className="settings-grid", children=[_appearance_card(theme), _plot_card("particle", "Particle Explorer", "blue", particle), _plot_card("sweep", "Parameter Sweep", "yellow", sweep)]),
+            html.Section(
+                className=Card.classes(color="blue", extra="panel settings-note"),
+                children=[
+                    html.Div(className="card-header panel-header", children=[html.H2("How settings are applied")]),
+                    html.Div(className="card-body", children=[html.P("Particle Explorer and Parameter Sweep remember separate plotting preferences. Polar coordinates are applied to trace-based plots when the representation supports them; heatmaps remain Cartesian."), html.Div(id="settings-save-status", className="settings-save-status", children="All settings are saved automatically.")]),
+                ],
+            ),
+        ],
+    )
+
+
+def _workspace_settings(stored: dict, key: str, defaults: dict) -> dict:
+    """Read nested preferences while tolerating the previous flat format."""
+    values = stored.get(key, stored if key == "particle_explorer" else {})
+    return {**defaults, **(values or {})}
+
+
+def _appearance_card(theme: str):
+    return html.Section(
+        className=Card.classes(color="blue", extra="panel settings-card"),
+        children=[
+            html.Div(className="card-header panel-header", children=[html.H2("Appearance")]),
+            html.Div(className="card-body settings-card-body", children=[html.Label("Theme", htmlFor="settings-theme-mode", className="settings-label"), _dropdown("settings-theme-mode", [{"label": "Light", "value": "light"}, {"label": "Dark", "value": "dark"}], theme if theme in {"light", "dark"} else DEFAULT_APPLICATION_SETTINGS["theme"]), html.P("The theme changes the dashboard shell and its controls.", className="settings-help")]),
+        ],
+    )
+
+
+def _plot_card(prefix: str, title: str, color: str, settings: dict):
+    return html.Section(
+        className=Card.classes(color=color, extra=f"panel settings-card settings-{prefix}-card"),
+        children=[
+            html.Div(className="card-header panel-header", children=[html.H2(title), html.Span("Independent plotting preferences", className="settings-card-subtitle")]),
+            html.Div(
+                className="card-body settings-card-body settings-form-grid",
+                children=[
+                    _number_setting("Font size", f"settings-{prefix}-font-size", settings["font_size"], 8, 32, 1),
+                    _number_setting("Line width", f"settings-{prefix}-line-width", settings["line_width"], 0.5, 8, 0.5),
+                    _number_setting("Graph height (px)", f"settings-{prefix}-graph-height", settings["graph_height"], 300, 1400, 10),
+                    _dropdown_field("Plot theme", f"settings-{prefix}-template", [{"label": "Match application theme", "value": "match-theme"}, {"label": "Light plot", "value": "plotly_white"}, {"label": "Dark plot", "value": "plotly_dark"}], settings["template"]),
+                    _dropdown_field("Coordinates", f"settings-{prefix}-coordinates", [{"label": "Cartesian", "value": "cartesian"}, {"label": "Polar (when supported)", "value": "polar"}], settings["coordinate_system"]),
+                    _dropdown_field("X-axis scale", f"settings-{prefix}-x-scale", [{"label": "Linear", "value": "linear"}, {"label": "Logarithmic", "value": "log"}], settings["x_scale"]),
+                    _dropdown_field("Legend", f"settings-{prefix}-legend", [{"label": "Show", "value": True}, {"label": "Hide", "value": False}], bool(settings["show_legend"])),
+                    _dropdown_field("Grid", f"settings-{prefix}-grid", [{"label": "Show", "value": True}, {"label": "Hide", "value": False}], bool(settings["show_grid"])),
+                    _dropdown_field("Y-axis scale", f"settings-{prefix}-log-y", [{"label": "Linear", "value": False}, {"label": "Logarithmic", "value": True}], bool(settings["log_y"])),
+                ],
+            ),
+        ],
+    )
+
+
+def _dropdown_field(label: str, component_id: str, options: list[dict], value):
+    return html.Div(className="settings-field", children=[html.Label(label, htmlFor=component_id, className="settings-label"), _dropdown(component_id, options, value)])
+
+
+def _dropdown(component_id: str, options: list[dict], value):
+    return dcc.Dropdown(id=component_id, options=options, value=value, clearable=False, searchable=False, optionHeight=38, maxHeight=200, persistence=True, persistence_type="session", className="dashboard-dropdown")
+
+
+def _number_setting(label: str, component_id: str, value: int | float, minimum: int | float, maximum: int | float, step: int | float):
+    return html.Div(className="settings-field", children=[html.Label(label, htmlFor=component_id, className="settings-label"), dcc.Input(id=component_id, type="number", value=value, min=minimum, max=maximum, step=step, placeholder=str(value), persistence=True, persistence_type="session", className="settings-number-input")])

PyMieSimX/gui/pages/single/__init__.py

@@ -0,0 +1,5 @@
+"""Single-particle page and sections."""
+
+from .page import build_single_page
+
+__all__ = ["build_single_page"]

PyMieSimX/gui/pages/single/page.py

@@ -0,0 +1,28 @@
+"""Single-particle page composition."""
+
+from dash import dcc, html
+
+from PyMieSimX.gui.components import HeaderCard
+from PyMieSimX.gui.layout import PLOT_CONFIG, _plot_options_card
+
+from .sections import build_representation_section, build_scatterer_section, build_source_section
+
+
+def build_single_page(plot_settings: dict | None = None):
+    """Build the single page from independent setup and plot sections."""
+    return html.Div(
+        className="tab-content-stack single-tab-content",
+        children=[
+            HeaderCard(
+                "Particle Explorer",
+                "Inspect angular scattering, polarization, and field patterns for one source–scatterer setup.",
+                [
+                    ("01", "Configure source", "Choose a source and set its optical parameters.", "yellow"),
+                    ("02", "Configure scatterer", "Define the particle geometry and refractive indices.", "blue"),
+                    ("03", "Choose representation", "Inspect amplitudes, polarization, phase functions, or far fields.", "orange"),
+                ],
+                color="green",
+            ).render(),
+            html.Section(className="single-workspace", children=[html.Section(className="control-column", children=[build_source_section(), build_scatterer_section()]), html.Section(className="result-column", children=[html.Section(className="panel graph-panel single-graph-panel", children=[dcc.Loading(id="single-graph-loading", type="circle", color="#4f8df7", custom_spinner=html.Div("Computing…", className="plot-computing-indicator"), delay_show=150, delay_hide=150, children=html.Div(className="plot-loading-target", children=[dcc.Graph(id="single-graph", config=PLOT_CONFIG), html.Div(id="single-computation-status", style={"display": "none"})]))]), build_representation_section(), html.Div(id="single-plot-options-container", children=[_plot_options_card("single", plot_settings or {})]), html.Div(className="export-actions", children=[html.Button("Export CSV", id="export-single-csv", n_clicks=0, className="run-button export-button")])])]),
+        ],
+    )

PyMieSimX/gui/pages/single/sections/__init__.py

@@ -0,0 +1,6 @@
+"""Sections composing the single-particle page."""
+
+from .representations import build_representation_section
+from .setup import build_scatterer_section, build_source_section
+
+__all__ = ["build_representation_section", "build_scatterer_section", "build_source_section"]

PyMieSimX/gui/pages/single/sections/representations.py

@@ -0,0 +1,38 @@
+"""Representation controls section."""
+
+from dash import dcc, html
+
+from PyMieSimX.gui.components import Card
+from PyMieSimX.gui.defaults import DEFAULT_WORKSPACE_SETTINGS
+
+def build_representation_section():
+    return html.Section(
+        id="single-representation-card",
+        className=Card.classes(color="blue", extra="workflow-card representation-card"),
+        children=[
+            html.Div(className="representation-card-header", children=[html.Span("Representation Controls")]),
+            html.Div(
+                id="single-representation-body",
+                className="workflow-card-body representation-card-body",
+                children=[
+                    html.Div(id="single-nearfield-availability-alert", className="nearfield-availability-alert", style={"display": "none"}),
+                    html.Div(
+                        className="representation-controls-row",
+                        children=[
+                            html.Div(className="field-block", children=[html.Label("Representation", htmlFor="single-representation"), dcc.Dropdown(id="single-representation", className="dashboard-dropdown", options=[{"label": "S1 / S2 amplitudes", "value": "s1s2"}, {"label": "Stokes I intensity", "value": "stokes"}, {"label": "Stokes Q", "value": "stokes_q"}, {"label": "Stokes U", "value": "stokes_u"}, {"label": "Stokes V", "value": "stokes_v"}, {"label": "Scattering phase function", "value": "spf"}, {"label": "Far-field intensity", "value": "farfields"}, {"label": "Near-field E", "value": "nearfields"}, {"label": "Near-field Ex", "value": "nearfields_ex"}, {"label": "Near-field Ey", "value": "nearfields_ey"}, {"label": "Near-field Ez", "value": "nearfields_ez"}], value=DEFAULT_WORKSPACE_SETTINGS["particle_explorer"]["representation"], clearable=False, searchable=False, optionHeight=38, maxHeight=400, persistence=True, persistence_type="session")]),
+                            html.Div(className="field-block", children=[html.Label("Projection", htmlFor="single-projection"), dcc.Dropdown(id="single-projection", className="dashboard-dropdown", options=[{"label": "2D plot", "value": "2d"}, {"label": "Polar 1D", "value": "polar_1d"}], value=DEFAULT_WORKSPACE_SETTINGS["particle_explorer"]["projection"], clearable=False, searchable=False, optionHeight=38, maxHeight=400, persistence=True, persistence_type="session")]),
+                            html.Div(className="field-block sampling-field", children=[html.Label("Angular sampling", htmlFor="single-sampling"), dcc.Input(id="single-sampling", type="text", inputMode="numeric", value=str(DEFAULT_WORKSPACE_SETTINGS["particle_explorer"]["sampling"]), placeholder=str(DEFAULT_WORKSPACE_SETTINGS["particle_explorer"]["sampling"]), className="field-input", persistence=True, persistence_type="session")]),
+                        ],
+                    ),
+                    html.Div(
+                        id="single-nearfield-controls-row",
+                        className="nearfield-controls-row",
+                        children=[
+                            html.Div(id="single-nearfield-mode-field", className="field-block", children=[html.Label("Abs", htmlFor="single-nearfield-mode"), dcc.Checklist(id="single-nearfield-mode", options=[{"label": "", "value": "absolute"}], value=["absolute"], className="nearfield-switch", persistence=True, persistence_type="session")]),
+                            html.Div(id="single-nearfield-incident-field", className="field-block", children=[html.Label("Incident field", htmlFor="single-include-incident-field"), dcc.Checklist(id="single-include-incident-field", options=[{"label": "", "value": "include"}], value=["include"], className="nearfield-switch", persistence=True, persistence_type="session")]),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )

PyMieSimX/gui/pages/single/sections/setup.py

@@ -0,0 +1,27 @@
+"""Source and scatterer setup section."""
+
+from dash import dcc, html
+
+from PyMieSimX.gui.components import Card
+from PyMieSimX.gui.defaults import DEFAULT_WORKSPACE_SETTINGS
+from PyMieSimX.gui.schemas import SINGLE_SCATTERER_FIELDS, SINGLE_SOURCE_FIELDS
+
+
+def build_source_section():
+    return _setup_card("Source Set", "single-source-type", "single-source-fields", SINGLE_SOURCE_FIELDS, DEFAULT_WORKSPACE_SETTINGS["particle_explorer"]["source_type"], color="yellow", info="Configure the optical source and its wavelength, polarization, power, and aperture values.")
+
+
+def build_scatterer_section():
+    return _setup_card("Scatterer Set", "single-scatterer-type", "single-scatterer-fields", SINGLE_SCATTERER_FIELDS, DEFAULT_WORKSPACE_SETTINGS["particle_explorer"]["scatterer_type"], color="blue", info="Configure particle geometry, material, and surrounding medium values.")
+
+
+def _setup_card(title, selector_id, fields_id, choices, default, color="blue", info=""):
+    return html.Details(
+        id=f"{selector_id}-card",
+        className=Card.classes(color=color, extra="workflow-card"),
+        open=True,
+        children=[
+            html.Summary(children=[html.Span(title), html.Span("i", className="workflow-info-button", title=info, **{"aria-label": info})]),
+            html.Div(className="workflow-card-body", children=[dcc.Dropdown(id=selector_id, className="dashboard-dropdown", options=[{"label": key, "value": key} for key in choices], value=default, clearable=False, searchable=False, optionHeight=38, maxHeight=200, persistence="particle-explorer-defaults-v3", persistence_type="session"), html.Div(id=fields_id, className="panel-body")]),
+        ],
+    )

PyMieSimX/gui/parsing.py

@@ -0,0 +1,149 @@
+"""Parsing helpers for dashboard form values."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from PyMieSim.experiment.polarization_set import PolarizationSet
+from PyMieSim.material import SellmeierMaterial, SellmeierMedium, TabulatedMaterial
+
+
+def parse_expression(raw_value: Any) -> Any:
+    """Parse a scalar, CSV sequence, or ``start:end:count`` specification."""
+    if raw_value is None:
+        return None
+
+    if isinstance(raw_value, (int, float, complex, np.ndarray, list, tuple)):
+        return raw_value
+
+    text = str(raw_value).strip()
+
+    if text == "":
+        return None
+
+    if text.count(":") == 2:
+        start_text, stop_text, count_text = [part.strip() for part in text.split(":")]
+        count = int(float(count_text))
+        if count <= 0:
+            raise ValueError("Range count must be positive.")
+        return np.linspace(float(start_text), float(stop_text), count)
+
+    if "," in text:
+        tokens = [_parse_scalar_or_text(token.strip()) for token in text.split(",") if token.strip()]
+
+        if all(not isinstance(token, str) for token in tokens):
+            dtype = complex if any(isinstance(token, complex) and not isinstance(token, bool) for token in tokens) else float
+            return np.asarray(tokens, dtype=dtype)
+
+        return [str(token) for token in tokens]
+
+    return _parse_scalar_or_text(text)
+
+
+def parse_numeric_expression(raw_value: Any, *, integer: bool = False) -> Any:
+    """Parse a numeric scalar or numeric sequence."""
+    parsed = parse_expression(raw_value)
+
+    if parsed is None:
+        return None
+
+    if isinstance(parsed, str):
+        raise ValueError(f"Expected numeric values, received '{parsed}'.")
+
+    if isinstance(parsed, np.ndarray):
+        return parsed.astype(int if integer else float)
+
+    if isinstance(parsed, list):
+        if any(isinstance(value, str) for value in parsed):
+            raise ValueError(f"Expected numeric values, received '{parsed}'.")
+        return np.asarray(parsed, dtype=int if integer else float)
+
+    return int(parsed) if integer else float(parsed)
+
+
+def parse_quantity_expression(raw_value: Any, unit: Any) -> Any:
+    """Parse a numeric expression and attach a Pint unit."""
+    parsed = parse_numeric_expression(raw_value)
+
+    if parsed is None:
+        return None
+
+    return parsed * unit
+
+
+def parse_polarization(raw_value: Any, unit: Any) -> PolarizationSet:
+    """Parse a polarization angle expression into a ``PolarizationSet``."""
+    angles = parse_quantity_expression(raw_value, unit)
+    return PolarizationSet(angles=angles)
+
+
+def parse_mode_numbers(raw_value: Any) -> Any:
+    """Parse one or more coherent mode labels."""
+    parsed = parse_expression(raw_value)
+
+    if isinstance(parsed, list):
+        return parsed
+
+    return parsed
+
+
+def parse_material_values(raw_value: Any, *, medium: bool = False) -> Any:
+    """Parse numeric or named material or medium definitions."""
+    parsed = parse_expression(raw_value)
+
+    if parsed is None:
+        return None
+
+    if isinstance(parsed, np.ndarray):
+        return parsed
+
+    if isinstance(parsed, list):
+        return [_resolve_material_entry(value, medium=medium) for value in parsed]
+
+    return _resolve_material_entry(parsed, medium=medium)
+
+
+def serialize_value(value: Any) -> Any:
+    """Convert NumPy and object values into JSON-friendly primitives."""
+    if isinstance(value, np.generic):
+        return value.item()
+
+    if isinstance(value, complex):
+        return str(value)
+
+    if isinstance(value, (int, float, str, bool)) or value is None:
+        return value
+
+    return str(value)
+
+
+def _parse_scalar_or_text(text: str) -> Any:
+    """Parse one scalar token as float, complex, or raw text."""
+    if text == "":
+        return None
+
+    try:
+        if "j" in text.lower():
+            return complex(text.replace("i", "j").replace("I", "j"))
+        return float(text)
+    except ValueError:
+        return text
+
+
+def _resolve_material_entry(value: Any, *, medium: bool) -> Any:
+    """Resolve one material token into either a numeric value or material object."""
+    if not isinstance(value, str):
+        return value
+
+    constructors = (SellmeierMedium,) if medium else (SellmeierMaterial, TabulatedMaterial)
+    last_error = None
+
+    for constructor in constructors:
+        try:
+            return constructor(value)
+        except Exception as error:  # pragma: no cover
+            last_error = error
+
+    raise ValueError(f"Unknown {'medium' if medium else 'material'} '{value}'.") from last_error