OpenPhysics is a Python simulation toolkit for electromagnetic fields, heat conduction and solid mechanics. It brings finite-element solvers, meshing, material models and independent reference solutions into one repository. Use the Python APIs directly, run supported models from JSON, or explore 2D optical models and heat documents, rectangular or with material regions, in the local browser Studio.
The project is under active development. Each feature has an explicit contract and validation scope; the name does not imply a general-purpose coupled multiphysics solver.
The waveguide tutorial (한국어) takes a silicon strip from the supplied example to your own strip, rib or polygon cross-section: effective index, mode fields and group index, with the window, mesh and slab-mode checks that tell you whether to trust them.
For an interactive first study, the experimental Studio workspace
(한국어) lets you edit an
optical cross-section from rectangles, circles and polygons of ten lossless
materials, inspect its mesh, run modes, compare designs and save or recover a
session; its steady heat application solves one homogeneous rectangular plate
with a condition per side. After installing simcase[studio] in the configured
runtime, launch it with simcase-studio --workspace. The heated-waveguide
application card is setup only: electrical heating and mechanical deformation
do not run in this workspace yet.
| Area | Implemented scope | Guide |
|---|---|---|
| Electromagnetics | 2D scalar and full-vector waveguide modes; resolved-mode wavelength sweeps with complex fields and mode tracking | Model runner, vector reliability |
| Electrostatics and scattering | 2D electrostatic potential and frequency-domain Helmholtz scattering with a first-order absorbing boundary or a cylindrical PML, through the Python API | galerkin, milestone validation |
| 3D cavities | Rectangular-box eigenmodes, vacuum PEC or with lossy box materials and conducting walls (complex frequencies and Q), through a Python API or a single JSON study | Cavity API, material cavity, JSON contract |
| Electric conduction | Steady isotropic 2D Python API; region conductivity, voltage/current/insulation, explicit Neumann gauges, V/E/J and Joule heat | Electric API and coupling contract |
| Heat conduction | Steady isotropic 2D conduction; Dirichlet, prescribed-flux and Robin boundaries; rectangular headless JSON with side-constant boundary data and a dedicated Studio view | Heat API, flux/Robin, thermal JSON, boundary JSON, Studio |
| Transient heat | 2D Python engine and rectangular headless JSON/API/CLI/save; fixed P1, consistent mass/backward Euler, constant isotropic properties, explicit times and sampled Dirichlet/insulation; dedicated Studio time/field/history views | Transient heat, document, validation, Studio |
| Material regions | Piecewise-constant isotropic materials on named 2D mesh regions for steady and transient heat, elasticity, thermal expansion and both heat→mechanics workflows in Python; steady and transient heat JSON documents with shapes over a background | Region materials, region documents |
| Solid mechanics | Static 2D linear elasticity, plane stress/strain and global Cartesian boundary traction; a headless rectangular JSON document with side displacement components, side tractions and a constant body force | Elasticity, traction, JSON contract |
| Thermal expansion | Prescribed nodal-temperature mechanics, optional total traction, and an explicit same-mesh steady heat→mechanics workflow; a headless rectangular JSON document that solves steady heat and then thermal stress | Prescribed temperature, total traction, workflow, JSON contract |
| Joule heating | Same-mesh steady electric/heat Python workflows; constant or temperature-dependent conductivity, elementwise power transfer and thermal energy balance | Joule workflow |
| Transient thermal stress | Quasistatic linear small-strain mechanics at selected stored transient-heat times on the same fixed mesh, through an explicit second Python call | Transient heat→mechanics |
| Feature | Python API | JSON / CLI | Studio |
|---|---|---|---|
| 2D waveguide modes and sweeps | Yes | em.modes2d (passive absorption supported) |
Yes |
| 2D electrostatics and scattering | Yes | No | No |
| 3D cavity: vacuum PEC, lossy materials and walls | Yes | em.cavity3d |
No |
| Steady electric conduction | Yes | Homogeneous rectangle | No |
| Steady heat | Yes | Rectangular thermal.steady2d |
Dedicated view; workspace heat plate |
| Transient heat | Yes | Rectangular thermal.transient2d |
Dedicated views |
| Heat with material regions | Yes | thermal.steady2d, thermal.transient2d with shapes |
Dedicated views, within region limits |
| Linear elasticity | Yes | Homogeneous rectangle mechanics.elasticity2d |
No |
| Steady heat→thermal stress | Yes | Homogeneous rectangle mechanics.thermoelastic2d |
No |
| Prescribed-temperature and transient heat→mechanics | Yes | No | No |
| Steady Joule heating | Yes | Homogeneous rectangle, constant or σ(T) | No |
Python-only capabilities do not automatically appear in JSON or Studio.
With the optional simcase[export] extra, saved results can be written as VTU
files for ParaView: rectangular steady heat, including flux and convection sides,
rectangular transient heat, steady/transient heat with material regions,
electric conduction and Joule heating, linear elasticity and thermal stress, and the cavities (vacuum PEC,
or materials and lossy walls). Transient heat supports one time or every stored
time as a .pvd series. See Viewing in ParaView.
- Heat→mechanics coupling is one-way: an explicit second Python call with no feedback to heat. Fully coupled thermal feedback is not supported.
- Transient heat has no restart, transient flux/Robin input or automatic coupling.
- The steady heat→mechanics workflow does not yet accept the separate Robin/flux/traction extensions.
- Prescribed-temperature and transient heat→mechanics and 2D electrostatics and scattering are Python-only; the mechanics documents cover one homogeneous rectangle with side-constant data (isothermal elasticity, or steady heat then thermal stress), with no regions.
- 2D heat and mechanics are plane models per unit depth. JSON heat documents set boundary conditions only on the four outer sides of the domain.
em.modes2dsupports passive absorption and PML/leaky/constant-radius modes; candidates require independent PML/mesh convergence checks. Variable curvature, nonlinear mechanics and geometry sweeps are not supported.- Studio rejects 3D models and mechanics documents, takes heat documents with material regions only within its region limits, and has no mechanics forms.
- The VTU export rejects waveguide modes. Steady heat and Joule documents
include their flux/Robin load arrays; complex cavity fields are written as
_real/_imagpairs; elasticity and thermoelastic strain and stress become named scalar components.
All implementation sources and their documentation are available here. Each package has its own distribution, version, dependencies and license notices.
| Package | Purpose |
|---|---|
| galerkin | Finite-element engines and field postprocessing |
| galerkin-refsol | Independent analytical references and published benchmarks; import as refsol |
| meshine | 2D triangle meshes for material regions, and layered tetrahedral meshes |
| meshloom | Tetrahedral mesher with a compiled exact-arithmetic kernel; exact predicates and Delaunay kernel, no mesher yet |
| gmshio | Optional Gmsh executable integration, MSH reader and mesh adapters |
| physmat | Material properties, optical dispersion and Drude–Lorentz fitting |
| simcase | JSON documents, headless runner and optional local Studio |
| sipi | Signal and power integrity: quasi-static PCB transmission-line cross-sections |
The ninth distribution, openphysics
(0.0.1), only reserves the project name: it contains no engine and does not
install these packages. The repository root is not an installable distribution.
Use the checkout installation below; pip install openphysics does not install
the simulation toolkit.
CI runs the full regression on CPython 3.12 and Ubuntu 24.04. For a Linux checkout:
git clone https://github.com/fieldalgo/openphysics.git
cd openphysics
python -m venv .venv
source .venv/bin/activate
python -m pip install -e packages/galerkin -e packages/galerkin-refsol -e packages/meshine -e packages/gmshio -e "packages/physmat[rii]" -e "packages/simcase[studio,test]" -e packages/sipimeshloom builds a compiled Rust kernel: install it with a Rust toolchain on the
path (rustup; the version is pinned in packages/meshloom/rust-toolchain.toml)
and maturin, for example python -m pip install maturin -e packages/meshloom.
Run commands from the repository root. Running Python inside packages/ can
shadow installed modules with the directories of the same name.
Gmsh is optional and separately installed: mesh generation needs gmsh on PATH
or GMSH_EXECUTABLE; reading existing MSH files does not. Built-in optical
materials work without downloading the full refractiveindex.info database.
For pinned dependency and database versions, use the development guide.
Validate and run the supplied slab-waveguide document:
python -m simcase validate examples/simcase/slab_te_check.json
python -m simcase run examples/simcase/slab_te_check.json -o slab_resultsExplore 2D optical models and heat documents in Studio:
python -m simcase.studio --no-browserOpen http://127.0.0.1:8765. Studio is a local tool, not an authenticated
multi-user service. Keep it off untrusted networks. CLI entry points are
simcase, simcase-run and simcase-studio; the document format retains
"openphysics": "0.2" as its version field.
Try a headless heat document or standalone Python examples:
python -m simcase run examples/simcase/thermal_slab.json -o thermal_results
python examples/galerkin/thermal_steady2d.py
python examples/galerkin/elasticity_traction.py
python examples/galerkin/thermoelastic_traction.pyMore documents are in examples/simcase and
more scripts in examples/galerkin.
Use a fresh output directory for each saved run and retain exclusive control until saving and cleanup finish. Hostile filesystem races and atomic rollback are outside acceptance. Read each contract for units: thermal APIs use Kelvin, heat flow per depth is W/m, mechanical force per depth is N/m and physical elastic energy per depth is J/m.
Physics features are checked against independent analytical references, conservation identities, negative controls and mesh-convergence studies. Each feature's criteria and limits are in its contract and validation documents, linked from the documentation index. Run the full source suite from the repository root:
python -m pytest -q| Scope | Platforms | What it covers |
|---|---|---|
| Full source regression | Linux, Python 3.12 | Full source suite, Studio JavaScript checks, all nine distributions built and installed, numerically sensitive tests under two forced BLAS kernels |
| Installed-package acceptance | Linux, macOS, Windows, Python 3.12 | Linux: every Python test against all nine wheels, built from sdists and installed with their extras outside the checkout. Each OS: eight implementation sdists built into wheels and tested in a fresh environment for package bytes, bundled assets, public API/CLI/save behavior and heat save/I-O robustness |
Installed acceptance is not a full macOS or Windows regression. Package metadata
requires Python 3.12 or later, and CI tests only Python 3.12; OS Independent classifiers
and py3-none-any wheels describe metadata, not a tested platform matrix. meshloom's compiled
wheels are built for manylinux 2.17 x86_64 and aarch64, macOS 11 x86_64 and arm64, and
Windows x64; CI installs and tests the ones for its own runners only. A
commit's results are in its required tests check on GitHub Actions. The
development guide lists the checks and commands.
| Page | Content |
|---|---|
| Documentation home | Choose a reading route, in English or Korean |
| Getting started | Installation, first model and examples |
| Build a model | Geometry, materials, mesh and package composition |
| Physics problems | Electromagnetics, heat, electric/Joule and mechanics/coupling |
| Execution guide | Python, JSON/CLI and Studio routes |
| Results and trust | Saved fields, export, conservation and convergence |
| API and document contracts | Package inputs, outputs, units and limits |
| Theory and numerical methods | Formulations behind the implemented solvers |
| Validation and benchmarks | Independent references, measured scope and historical records |
| Developer guide | Environment, CI, contribution and documentation maintenance |
Usage and validation guides under docs/ have complete Korean counterparts;
start from the Korean index.
See CONTRIBUTING.md for changes, bug reports and questions, and
SECURITY.md for private vulnerability reporting. The default
branch, main, contains reviewed changes; feature branches may contain
unvalidated work.
Original code and documentation are licensed under Apache-2.0. NOTICE and package notices preserve third-party terms: embedded refractiveindex.info optical data is CC0 1.0, Gmsh is separately installed under its own license, and dependency licenses are not replaced by this repository's license.
Every dependency, external program, dataset and published reference, with its license and how it is used, is listed in third-party software.
Temperature-dependent two-way coupling: Python API.
Electric conduction and constant/temperature-dependent Joule heating: JSON/CLI contract and examples.