polarism 0.3.2__tar.gz

polarism-0.3.2/LICENSE

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

polarism-0.3.2/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: polarism
+Version: 0.3.2
+Summary: High-performance tools for driven-dissipative exciton-polariton simulations
+Author: Jakub Rogala
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jakrog01/Polarism
+Project-URL: Repository, https://github.com/jakrog01/Polarism
+Project-URL: Documentation, https://jakrog01.github.io/Polarism/
+Project-URL: Issues, https://github.com/jakrog01/Polarism/issues
+Project-URL: Changelog, https://github.com/jakrog01/Polarism/releases
+Keywords: exciton-polariton,gross-pitaevskii,driven-dissipative,physics-simulation,cuda
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h5py>=3.15
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: numpy>=2.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.67
+Requires-Dist: tyro>=0.9
+Provides-Extra: cuda12
+Requires-Dist: cupy-cuda12x>=13; extra == "cuda12"
+Provides-Extra: cuda13
+Requires-Dist: cupy-cuda13x>=14; extra == "cuda13"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.7; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=8.3; extra == "test"
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.7; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Dynamic: license-file
+
+> "The test of a first-rate intelligence is the ability to hold two opposed ideas in the mind at the same time, and still retain the ability to function." ~ F. Scott Fitzgerald
+
+# Polarism
+
+High-performance tools for 2-D driven-dissipative Gross-Pitaevskii
+simulations of exciton-polariton systems.
+
+The repository is organized around one clear boundary:
+
+- `polarism/` is the physics engine: model configuration, grids, lasers,
+  reservoirs, solvers, state evolution, and result storage.
+- `tests/` contains the validation layer for the engine and solver behavior.
+- `examples/` contains runnable usage examples.
+
+The full documentation site is in `docs/` and is configured by `mkdocs.yml`.
+
+Documentation site:
+https://jakrog01.github.io/Polarism/#getting-started
+
+## Repository Layout
+
+```text
+polarism/                     Physics engine and reusable Python package
+  config/                     Dataclasses and validation helpers
+  grid/                       Periodic and closed-interval 2-D grids
+  laser/                      Continuous and pulsed pump definitions
+  reservoir/                  Single, double, and quadratic-double reservoirs
+  solver/                     CPU, CuPy, CUDA RK4, FFT, and ETD/IP solvers
+  results/                    Storage and visualization support
+
+tests/                        CPU, compliance, and benchmark-style tests
+
+docs/                         MkDocs Material documentation site
+examples/                     Runnable usage examples
+pyproject.toml                Project metadata and dependency groups
+```
+
+## Installation
+
+```bash
+pip install polarism
+```
+
+GPU solvers additionally need a CuPy build matching the local CUDA toolkit,
+e.g. `pip install "polarism[cuda12]"` or `pip install "polarism[cuda13]"`; see
+[`docs/getting-started/installation.md`](https://github.com/jakrog01/Polarism/blob/master/docs/getting-started/installation.md).
+
+## Quick Local Setup
+
+For development, use the project virtual environment. The global Python on the target systems is
+not expected to contain the required packages.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+Run the default CPU-oriented checks:
+
+```bash
+.venv/bin/pytest
+.venv/bin/mkdocs build
+```
+
+The default pytest selection excludes slow and compliance-marked suites. See
+[`docs/development/testing-and-ci.md`](https://github.com/jakrog01/Polarism/blob/master/docs/development/testing-and-ci.md) for
+the heavier validation commands.
+
+For the complete CPU/GPU validation, including the Phoenix reference matrix:
+
+```bash
+.venv/bin/pytest -q -m '' --use-gpu --tb=short \
+  --junitxml=artifacts/reports/full_verification.xml
+```
+
+Run this command as a single process with exclusive access to the GPU.
+
+## Minimal API Example
+
+The same script is available as [`examples/basic_run.py`](https://github.com/jakrog01/Polarism/blob/master/examples/basic_run.py).
+
+```python
+import polarism as ps
+from polarism.compute_engine import compute_engine
+
+cfg = ps.Config()
+
+cfg.grid.nx = 128
+cfg.grid.ny = 128
+cfg.grid.lx = 100.0
+cfg.grid.ly = 100.0
+cfg.grid.grid_type = "periodic"
+
+cfg.reservoir.reservoir_type = "single"
+cfg.potential.potential_type = "zero"
+
+cfg.laser.mode = "single"
+cfg.laser.laser_type = "continuous-gaussian"
+cfg.laser.P0 = 0.02
+cfg.laser.sigma_space = 12.0
+
+cfg.solver.method = "rk4-fdm"
+cfg.solver.dt = 1e-3
+cfg.solver.total_time = 2.0
+
+cfg.result.save_results = True
+cfg.result.save_hdf5 = True
+cfg.result.output_directory = "quickstart_results"
+
+cfg.compute_engine.use_gpu = False
+compute_engine.configure(cfg.compute_engine)
+
+ps.SimulationController(cfg).run()
+```
+
+For the command-line interface generated from `polarism.Config`:
+
+```bash
+.venv/bin/polarism --help
+```
+
+More examples are documented in
+[`docs/getting-started/quickstart.md`](https://github.com/jakrog01/Polarism/blob/master/docs/getting-started/quickstart.md).
+
+## Pump Power Conventions
+
+For pulsed pumps, prefer explicit physical semantics in the laser YAML:
+
+```yaml
+lasers:
+  - laser_type: pulse-gaussian
+    power_definition: pulse_energy
+```
+
+`pulse_energy` means that `power` / `P` is the integrated dose of one pulse
+over space and time. This keeps spot-size sweeps meaningful: increasing
+`sigma_space` lowers the local peak pump while preserving the total pulse dose.
+The legacy `peak_amplitude` mode is still available for reproducing old runs.
+
+Numerical choices such as grid spacing, timestep, boundary condition, kinetic
+relaxation, and Laplacian stencil should be treated as convergence parameters,
+not as cosmetic post-processing settings. The model background and rationale are
+summarized in
+[`docs/development/physics-background.md`](https://github.com/jakrog01/Polarism/blob/master/docs/development/physics-background.md).
+
+## Documentation
+
+Build and serve the documentation locally:
+
+```bash
+.venv/bin/mkdocs serve
+```
+
+Key entry points:
+
+- [`docs/index.md`](https://github.com/jakrog01/Polarism/blob/master/docs/index.md) for the documentation map.
+- [`docs/getting-started/installation.md`](https://github.com/jakrog01/Polarism/blob/master/docs/getting-started/installation.md)
+  for setup.
+- [`docs/user-guide/grid-and-parameters.md`](https://github.com/jakrog01/Polarism/blob/master/docs/user-guide/grid-and-parameters.md)
+  for spatial discretization and physical parameters.
+- [`docs/user-guide/potentials-and-pumps.md`](https://github.com/jakrog01/Polarism/blob/master/docs/user-guide/potentials-and-pumps.md)
+  for laser and pump definitions.
+- [`docs/user-guide/output-and-visualization.md`](https://github.com/jakrog01/Polarism/blob/master/docs/user-guide/output-and-visualization.md)
+  for HDF5 output, plots, and movies.
+
+## Development Notes
+
+- Keep reusable physics logic inside `polarism/`.
+- Keep tests for engine behavior inside `tests/`.
+- Use `.venv/bin/python`, `.venv/bin/pytest`, and `.venv/bin/mkdocs` in this
+  repository.
+
+## Acknowledgements
+
+This project is developed with the Exciton-Polariton research group at the
+Faculty of Physics, University of Warsaw, with support from NCN OPUS grant work
+and ICM computing infrastructure.

polarism-0.3.2/README.md

@@ -0,0 +1,179 @@
+> "The test of a first-rate intelligence is the ability to hold two opposed ideas in the mind at the same time, and still retain the ability to function." ~ F. Scott Fitzgerald
+
+# Polarism
+
+High-performance tools for 2-D driven-dissipative Gross-Pitaevskii
+simulations of exciton-polariton systems.
+
+The repository is organized around one clear boundary:
+
+- `polarism/` is the physics engine: model configuration, grids, lasers,
+  reservoirs, solvers, state evolution, and result storage.
+- `tests/` contains the validation layer for the engine and solver behavior.
+- `examples/` contains runnable usage examples.
+
+The full documentation site is in `docs/` and is configured by `mkdocs.yml`.
+
+Documentation site:
+https://jakrog01.github.io/Polarism/#getting-started
+
+## Repository Layout
+
+```text
+polarism/                     Physics engine and reusable Python package
+  config/                     Dataclasses and validation helpers
+  grid/                       Periodic and closed-interval 2-D grids
+  laser/                      Continuous and pulsed pump definitions
+  reservoir/                  Single, double, and quadratic-double reservoirs
+  solver/                     CPU, CuPy, CUDA RK4, FFT, and ETD/IP solvers
+  results/                    Storage and visualization support
+
+tests/                        CPU, compliance, and benchmark-style tests
+
+docs/                         MkDocs Material documentation site
+examples/                     Runnable usage examples
+pyproject.toml                Project metadata and dependency groups
+```
+
+## Installation
+
+```bash
+pip install polarism
+```
+
+GPU solvers additionally need a CuPy build matching the local CUDA toolkit,
+e.g. `pip install "polarism[cuda12]"` or `pip install "polarism[cuda13]"`; see
+[`docs/getting-started/installation.md`](https://github.com/jakrog01/Polarism/blob/master/docs/getting-started/installation.md).
+
+## Quick Local Setup
+
+For development, use the project virtual environment. The global Python on the target systems is
+not expected to contain the required packages.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+Run the default CPU-oriented checks:
+
+```bash
+.venv/bin/pytest
+.venv/bin/mkdocs build
+```
+
+The default pytest selection excludes slow and compliance-marked suites. See
+[`docs/development/testing-and-ci.md`](https://github.com/jakrog01/Polarism/blob/master/docs/development/testing-and-ci.md) for
+the heavier validation commands.
+
+For the complete CPU/GPU validation, including the Phoenix reference matrix:
+
+```bash
+.venv/bin/pytest -q -m '' --use-gpu --tb=short \
+  --junitxml=artifacts/reports/full_verification.xml
+```
+
+Run this command as a single process with exclusive access to the GPU.
+
+## Minimal API Example
+
+The same script is available as [`examples/basic_run.py`](https://github.com/jakrog01/Polarism/blob/master/examples/basic_run.py).
+
+```python
+import polarism as ps
+from polarism.compute_engine import compute_engine
+
+cfg = ps.Config()
+
+cfg.grid.nx = 128
+cfg.grid.ny = 128
+cfg.grid.lx = 100.0
+cfg.grid.ly = 100.0
+cfg.grid.grid_type = "periodic"
+
+cfg.reservoir.reservoir_type = "single"
+cfg.potential.potential_type = "zero"
+
+cfg.laser.mode = "single"
+cfg.laser.laser_type = "continuous-gaussian"
+cfg.laser.P0 = 0.02
+cfg.laser.sigma_space = 12.0
+
+cfg.solver.method = "rk4-fdm"
+cfg.solver.dt = 1e-3
+cfg.solver.total_time = 2.0
+
+cfg.result.save_results = True
+cfg.result.save_hdf5 = True
+cfg.result.output_directory = "quickstart_results"
+
+cfg.compute_engine.use_gpu = False
+compute_engine.configure(cfg.compute_engine)
+
+ps.SimulationController(cfg).run()
+```
+
+For the command-line interface generated from `polarism.Config`:
+
+```bash
+.venv/bin/polarism --help
+```
+
+More examples are documented in
+[`docs/getting-started/quickstart.md`](https://github.com/jakrog01/Polarism/blob/master/docs/getting-started/quickstart.md).
+
+## Pump Power Conventions
+
+For pulsed pumps, prefer explicit physical semantics in the laser YAML:
+
+```yaml
+lasers:
+  - laser_type: pulse-gaussian
+    power_definition: pulse_energy
+```
+
+`pulse_energy` means that `power` / `P` is the integrated dose of one pulse
+over space and time. This keeps spot-size sweeps meaningful: increasing
+`sigma_space` lowers the local peak pump while preserving the total pulse dose.
+The legacy `peak_amplitude` mode is still available for reproducing old runs.
+
+Numerical choices such as grid spacing, timestep, boundary condition, kinetic
+relaxation, and Laplacian stencil should be treated as convergence parameters,
+not as cosmetic post-processing settings. The model background and rationale are
+summarized in
+[`docs/development/physics-background.md`](https://github.com/jakrog01/Polarism/blob/master/docs/development/physics-background.md).
+
+## Documentation
+
+Build and serve the documentation locally:
+
+```bash
+.venv/bin/mkdocs serve
+```
+
+Key entry points:
+
+- [`docs/index.md`](https://github.com/jakrog01/Polarism/blob/master/docs/index.md) for the documentation map.
+- [`docs/getting-started/installation.md`](https://github.com/jakrog01/Polarism/blob/master/docs/getting-started/installation.md)
+  for setup.
+- [`docs/user-guide/grid-and-parameters.md`](https://github.com/jakrog01/Polarism/blob/master/docs/user-guide/grid-and-parameters.md)
+  for spatial discretization and physical parameters.
+- [`docs/user-guide/potentials-and-pumps.md`](https://github.com/jakrog01/Polarism/blob/master/docs/user-guide/potentials-and-pumps.md)
+  for laser and pump definitions.
+- [`docs/user-guide/output-and-visualization.md`](https://github.com/jakrog01/Polarism/blob/master/docs/user-guide/output-and-visualization.md)
+  for HDF5 output, plots, and movies.
+
+## Development Notes
+
+- Keep reusable physics logic inside `polarism/`.
+- Keep tests for engine behavior inside `tests/`.
+- Use `.venv/bin/python`, `.venv/bin/pytest`, and `.venv/bin/mkdocs` in this
+  repository.
+
+## Acknowledgements
+
+This project is developed with the Exciton-Polariton research group at the
+Faculty of Physics, University of Warsaw, with support from NCN OPUS grant work
+and ICM computing infrastructure.

polarism-0.3.2/polarism/__init__.py

@@ -0,0 +1,57 @@
+"""Public package exports for polarism."""
+from polarism.boundary_conditions.boundary_condition import BoundaryCondition
+from polarism.config import Config
+from polarism.laser.laser_factory import LaserFactory
+from polarism.plugins import load_plugins
+from polarism.potential import create_potential
+from polarism.reservoir import create_reservoir
+from polarism.results import (
+    RealTimeVisualization,
+    ResultNode,
+    ResultProvider,
+    Results2D,
+    ResultScalar,
+    ResultScalarGroup,
+    ResultsManager,
+    ResultVisitor,
+    StorageVisitor,
+    VisualizationVisitor,
+    base_storage,
+    hdf5_storage,
+    json_storage,
+    npy_storage,
+)
+from polarism.simulation_controller import SimulationController
+from polarism.grid.simulation_grid_2d import SimulationGrid2D
+from polarism.simulation_state import SimulationState
+from polarism.solver import AbstractSolver, create_solver, RK4CudaSolver
+
+__version__ = "0.3.2"
+__all__ = [
+    "BoundaryCondition",
+    "Config",
+    "create_potential",
+    "create_reservoir",
+    "create_solver",
+    "AbstractSolver",
+    "RK4CudaSolver",
+    "LaserFactory",
+    "load_plugins",
+    "RealTimeVisualization",
+    "ResultNode",
+    "ResultProvider",
+    "SimulationController",
+    "SimulationGrid2D",
+    "SimulationState",
+    "Results2D",
+    "ResultScalar",
+    "ResultScalarGroup",
+    "ResultsManager",
+    "StorageVisitor",
+    "VisualizationVisitor",
+    "ResultVisitor",
+    "hdf5_storage",
+    "json_storage",
+    "npy_storage",
+    "base_storage",
+]

polarism-0.3.2/polarism/analysis/__init__.py

@@ -0,0 +1,28 @@
+"""Shared analysis primitives for polariton simulations."""
+from __future__ import annotations
+
+from polarism.analysis.condensation import (
+    CONDENSATION_PSI_SQ_FLOOR,
+    CondensationVerdict,
+    CrossingResult,
+    classify,
+    count_upward_crossings,
+    critical_reservoir_density,
+    gain_loss_signal,
+    integrate_zero_dim,
+    psi_sq_floor,
+    validate_sampling,
+)
+
+__all__ = [
+    "CONDENSATION_PSI_SQ_FLOOR",
+    "CondensationVerdict",
+    "CrossingResult",
+    "classify",
+    "count_upward_crossings",
+    "critical_reservoir_density",
+    "gain_loss_signal",
+    "integrate_zero_dim",
+    "psi_sq_floor",
+    "validate_sampling",
+]