Metadata-Version: 2.5
Name: magnelio
Version: 0.3.0
Summary: Python library for full-wave 3D electromagnetic field simulation
Project-URL: Homepage, https://github.com/brtkrtz/magnelio
Project-URL: Repository, https://github.com/brtkrtz/magnelio
Project-URL: Issues, https://github.com/brtkrtz/magnelio/issues
Author: Bernd Breitkreutz
License: LGPL-3.0-or-later
License-File: COPYING
License-File: COPYING.LESSER
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: h5py>=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numba>=0.59
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.12
Requires-Dist: vtk>=9.3
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
Requires-Dist: sphinx-gallery>=0.15; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == 'docs'
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=13.0; extra == 'gpu'
Provides-Extra: interop
Requires-Dist: scikit-rf; extra == 'interop'
Description-Content-Type: text/markdown

# Magnelio

[![CI](https://github.com/brtkrtz/magnelio/actions/workflows/ci.yml/badge.svg)](https://github.com/brtkrtz/magnelio/actions/workflows/ci.yml)
[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](COPYING.LESSER)

Magnelio is a Python library for full-wave 3D electromagnetic field
simulation.  Its standard workflow is broadband S-parameter extraction
over waveguide ports on arbitrary 3D geometry; the workhorse solver is
a time-domain Finite Integration Technique (FIT-TD) engine.

![Electric field vectors in a two-pole dielectric resonator filter: two ceramic pucks stand in a metal housing, separated by a wall with a coupling window, with a probe pin at each end](https://raw.githubusercontent.com/brtkrtz/magnelio/main/docs/_static/hero_dielectric_filter.png)

Performance is a design goal, not an afterthought: no field update ever
loops over cells in Python.  The time-stepping kernels are fused and
fully vectorised on three tiers — custom CUDA kernels on the GPU,
Numba-compiled multi-threaded kernels on the CPU, and pure array
stencils as the portable fallback — so a step runs at compiled-C speed,
and models with hundreds of geometric primitives and correspondingly
large grids stay tractable.

## Features

- FIT time-domain leapfrog solver on a structured non-uniform
  hexahedral grid, with conformal (sub-cell) material matrices
- NumPy (CPU) and CuPy (CUDA GPU) backends — `backend="auto"` uses the
  GPU when available, with CUDA-graph stepping
- Waveguide ports with exact discrete transparent boundaries (DTBC):
  TEM / QTEM / TE / TM / hybrid modes, multi-mode, declared on the
  model before meshing; lumped (RLC-backed) ports
- Boundary conditions: PEC, PMC, CPML, periodic, and symmetry planes —
  declared once on the model, carried by the mesh
- Materials: isotropic and diagonal-anisotropic, pole-residue
  dispersion for ε(ω)/μ(ω) with built-in vector fitting, conductor
  losses (perturbative or SIBC wall model), surface roughness
  (Hammerstad, Huray)
- Geometry: CSG primitives + Boolean operators (`a - b`, `a + b`,
  `a & b`), chainable transforms, and profile-based construction
  (loft, sweep, revolve, shell) via pythonocc-core
- Circuit elements embedded in the field solution: thin wires and
  lumped RLC networks
- Field monitors (time/frequency domain, flux, wall loss), plane-wave
  source (TF/SF), 3D eigenmode solver
- Antennas: near-to-far-field transform recorded on a Huygens box the
  monitor places by itself, with image theory for ground planes and
  symmetry planes — directivity, gain, realized gain, radiated power
  and efficiency, drawn as polar cuts or a 3D pattern surface
- Project store on disk: streamed results, bit-exact resume,
  post-processing on the stored data (HDF5 + ParaView/XDMF); every run
  generates a ready-to-open ParaView session (coloured per-solid
  geometry, slice planes, normalised field glyphs)
- Interop: Touchstone (`.sNp`) export and `scikit-rf` adapter

## Installation

Due to the dependency on pythonocc-core (Python bindings to
OpenCASCADE Technology), installation uses conda-forge; the most
convenient way is [miniforge3](https://github.com/conda-forge/miniforge).

In the magnelio directory, run:
```bash
mamba env create -f environment.yml
mamba activate mio
pip install -e .
```

A conda-forge package is planned as the primary channel, plus a
pip-only PyPI package covering everything except the CAD geometry
stack (the `geo` primitives and Boolean operators need pythonocc-core,
which exists only on conda-forge).

## Quick Start

S-parameters of a WR-90 rectangular waveguide section:

```python
import magnelio as mio
from magnelio import geo, ports

a, b, L = 22.86e-3, 10.16e-3, 40.0e-3   # WR-90 cross-section, length
f_max = 25.0e9

air = mio.Material.air()
model = mio.GeometryModel(background=air)   # walls: PEC by default
model.add(geo.Brick(origin=(0, 0, 0), size=(a, b, L), material=air))
model.add_port(ports.PortWaveguide(name="port1", plane="zmin", n_modes=3))
model.add_port(ports.PortWaveguide(name="port2", plane="zmax", n_modes=3))

mesh = mio.Mesh.from_geometry(
    model, mio.MeshControl(min_nodes_per_wavelength=15), f_max=f_max,
)

analysis = mio.AnalysisScatteringTD(mesh=mesh, f_max=f_max)
print(analysis.solve_ports()["port1"])   # mode table before the run

result = analysis.run(
    excited=[(p, m) for p in ("port1", "port2") for m in range(3)],
)
result.plot_s(("port2", "port1"), ("port1", "port1"))   # |S| over frequency
s21 = result.S("port2", "port1")         # complex S21 on result.f_axis
result.to_touchstone("wr90.s6p")         # 6 channels = 2 ports × 3 modes
```

Fourteen executable tutorials — from a first parallel-plate line to a
dielectric-resonator filter — live in
[`examples/tutorials/`](examples/tutorials/); they are the source of
the documentation's tutorial series.

## Documentation

[`docs/`](docs/) holds the Sphinx documentation: the tutorial series,
an API reference for the public surface (the core namespace and the
domain namespaces, generated from the docstrings) and the technical
method chapters — every numerical method with its literature source.
Build it locally with:

```bash
pip install -e .[docs]
sphinx-build -b html docs docs/_build/html
```

## Development

Magnelio is being built in an AI-assisted workflow ("vibe coding"):
the code is written in collaboration with LLM coding agents, with
method selection, validation targets and reviews set by the author.
Every numerical method is anchored to published literature in the
documentation's method chapters, and the test and validation suite —
not the authoring process — is the arbiter of correctness.

## License

Magnelio is free software, released under the **GNU Lesser General
Public License v3.0 or later** (LGPL-3.0-or-later) — see `COPYING`
and `COPYING.LESSER`. You may use it from proprietary code; changes
to magnelio itself must be published under the same license when
distributed.
