Electrostatics

This page covers the electrostatic solver in witwin.maxwell. It is a separate cell-centred finite-volume solver for the DC potential, not a low-frequency FDTD run. Use it to find the static potential and field around fixed-voltage or charged conductors, to extract an N-terminal capacitance matrix, or to seed an FDTD run with a DC field. All names on this page are exported from the top-level package (import witwin.maxwell as mw).

A solve follows the usual Scene, Simulation, Result flow:

1. Build a Scene with a Domain, a GridSpec, and boundary=mw.BoundarySpec.none(). The electrostatic solver sets its own outer boundary through ElectrostaticBoundarySpec, and any other scene boundary raises NotImplementedError.
2. Add dielectrics as ordinary Structure objects with non-dispersive materials. Add conductors with scene.add_electrostatic_terminal(...) and free charge with scene.add_charge_density(...). You can also pass lists to Scene(electrostatic_terminals=..., charge_densities=...).
3. Run mw.Simulation.electrostatic(scene, ...) or mw.Simulation.capacitance(scene, ...).
4. Read result.electrostatic (an ElectrostaticResultData) or result.capacitance (a CapacitanceData).

Units are SI: metres, volts, coulombs, farads, joules.

import witwin.maxwell as mw
 
scene = mw.Scene(
    domain=mw.Domain(bounds=((0.0, 0.5), (0.0, 0.5), (0.0, 0.5))),
    grid=mw.GridSpec.uniform(0.05),
    boundary=mw.BoundarySpec.none(),
)
boundary = mw.ElectrostaticBoundarySpec(
    default="neumann", z_low=("dirichlet", 1.0), z_high=("dirichlet", 0.0)
)
result = mw.Simulation.electrostatic(scene, boundary=boundary).run()
dc = result.electrostatic
print(dc.Ez.mean(), dc.energy)   # uniform field of 1 V / 0.5 m

Simulation.electrostatic#

mw.Simulation.electrostatic(scene, *, boundary=None, solver=None) -> ElectrostaticSimulation

Builds an electrostatic (Laplace/Poisson) run. Call .run() on the returned runner to get a Result with method="electrostatic".

Returns an ElectrostaticSimulation runner with two methods: prepare() compiles the scene and returns the compiled problem, and run() solves it and returns a Result. result.electrostatic is the ElectrostaticResultData. result.solver_stats holds iterations, residual, residual_abs, and gauss_error.

Raises TypeError if boundary or solver has the wrong type.

Simulation.capacitance#

mw.Simulation.capacitance(scene, *, terminals=None, reference=None, boundary=None,
                          solver=None, truncation_estimate=None) -> CapacitanceSimulation

Builds an N-terminal Maxwell capacitance-matrix extraction. For each active terminal it runs one solve with that terminal at 1 V and every other conductor at 0 V, and reads the induced charge on each terminal. Free charge from ChargeDensity sources is ignored. The terminals' own potential and charge settings do not affect the result.

Returns a CapacitanceSimulation runner with prepare() and run(). run() returns a Result with method="capacitance"; result.capacitance is the CapacitanceData. result.solver_stats holds reciprocity_error, row_sum_error, terminal_order, reference, and, with a truncation estimate, truncation_max_relative_delta and truncation_richardson_max_relative_shift.

Raises ValueError if the scene has no terminals, a name is unknown, no non-reference terminal remains, or there is no reference and no Dirichlet face.

scene = mw.Scene(domain=mw.Domain(bounds=((-1.0, 1.0),) * 3),
                 grid=mw.GridSpec.uniform(0.05), boundary=mw.BoundarySpec.none())
scene.add_electrostatic_terminal(
    mw.ElectrostaticTerminal(name="a", geometry=mw.Sphere(position=(-0.5, 0, 0), radius=0.18), potential=1.0))
scene.add_electrostatic_terminal(
    mw.ElectrostaticTerminal(name="b", geometry=mw.Sphere(position=(0.5, 0, 0), radius=0.18), potential=0.0))
cap = mw.Simulation.capacitance(scene).run().capacitance
print(cap.matrix, cap.mutual_capacitance("a", "b"))

ElectrostaticTerminal#

class ElectrostaticTerminal(name, geometry=None, structure=None, potential=None, charge=None, grounded=False)

Frozen equipotential conductor. It pins the potential of every cell whose centre lies inside its geometry (signed distance at most zero). Terminals live in Scene.electrostatic_terminals, never in the RF Scene.ports set. Terminals must not overlap, and each must cover at least one cell.

Raises ValueError if none of potential, charge, grounded=True is given, if both potential and charge are given, or if both or neither of geometry and structure are given. Raises TypeError for a geometry without signed_distance.

Property is_floating is True when the terminal has a prescribed charge and no potential.

mw.ElectrostaticTerminal(name="shield", geometry=mw.Box(position=(0, 0, 0), size=(0.2, 0.2, 0.2)), charge=0.0)

ChargeDensity#

class ChargeDensity(geometry, density)

Frozen volumetric free-charge source for the Poisson solve. Add it with scene.add_charge_density(...).

The compiler multiplies the density by each cell's occupancy and volume, so the per-cell free charge is in coulombs.

scene.add_charge_density(mw.ChargeDensity(geometry=mw.Box(position=(0, 0, 0), size=(0.5, 0.5, 0.5)), density=1.0e-6))

ElectrostaticBoundarySpec#

class ElectrostaticBoundarySpec(default='neumann', value=0.0, x_low=None, x_high=None,
                                y_low=None, y_high=None, z_low=None, z_high=None)

Frozen per-face outer boundary for the electrostatic domain. It is independent of the full-wave Scene.boundary.

'open' raises NotImplementedError. To model an isolated object, enlarge a grounded box until the result converges, and use TruncationEstimate to measure the remaining error.

Raises ValueError for an unknown kind or a non-zero value on a non-Dirichlet face.

Class methods#

ElectrostaticBoundarySpec.face#

ElectrostaticBoundarySpec.face(axis, side) -> tuple[str, float]

Returns the resolved (kind, value) for one face, for example face("z", "low"). Raises ValueError for an unknown face.

Property has_dirichlet is True when any face is Dirichlet.

spec = mw.ElectrostaticBoundarySpec(default="neumann", z_low=("dirichlet", 2.0))
assert spec.face("z", "low") == ("dirichlet", 2.0)
assert spec.face("z", "high") == ("neumann", 0.0)

ElectrostaticSolverConfig#

class ElectrostaticSolverConfig(tolerance=1e-10, max_iterations=20000, dtype=torch.float64)

Frozen settings for the Jacobi-preconditioned conjugate-gradient solve.

The solver stops at max_iterations without raising. Check ElectrostaticResultData.residual against your tolerance.

ElectrostaticResultData#

Typed output of Simulation.electrostatic(...).run(), read as result.electrostatic. All fields live on the cell-centred grid with shape (nx, ny, nz).

The fixed-potential solve is differentiable in the cell permittivity and in the free charge. Anisotropic (tensor) permittivity runs forward only and raises NotImplementedError when anything requires grad.

dc = result.electrostatic
print(dc.terminal_charge("inner"), dc.residual, dc.gauss_error)

CapacitanceData#

Typed output of Simulation.capacitance(...).run(), read as result.capacitance. matrix[i, j] is the charge in coulombs on active terminal i when terminal j is at 1 V and all other conductors are at 0 V, so it is also the Maxwell capacitance in farads. The matrix is reported raw, without symmetrization.

Matrix entries are differentiable in the cell permittivity.

CapacitanceData.capacitance#

CapacitanceData.capacitance(a, b) -> torch.Tensor

Returns the raw matrix entry C[a, b] in farads. Raises KeyError for a name not in terminal_order.

CapacitanceData.mutual_capacitance#

CapacitanceData.mutual_capacitance(a, b) -> torch.Tensor

Returns the coupling capacitance -C[a, b] in farads. Raises ValueError if a == b.

CapacitanceData.capacitance_to_reference#

CapacitanceData.capacitance_to_reference(a) -> torch.Tensor

Returns the row sum of C for terminal a: its capacitance to the reference, in farads.

CapacitanceData.two_terminal_capacitance#

CapacitanceData.two_terminal_capacitance(a=None, b=None) -> torch.Tensor

Returns the capacitance seen between terminals a and b with all other active terminals held at the reference: det / (Caa + Cbb + Cab + Cba) from the 2x2 submatrix. With no arguments it uses the two terminals of a 2x2 matrix.

Raises ValueError if the matrix is larger than 2x2 and you omit the names, or if a and b are equal.

TruncationEstimate#

class TruncationEstimate(padding_cells=8)

Frozen opt-in request for a domain-truncation estimate. Pass it to Simulation.capacitance(truncation_estimate=...).

The estimate needs a uniform GridSpec, a boundary with at least one Dirichlet face, and no dielectric structure touching the domain boundary. Otherwise run() raises ValueError.

result = mw.Simulation.capacitance(
    scene, terminals=("c",), boundary=mw.ElectrostaticBoundarySpec.grounded_box(),
    truncation_estimate=mw.TruncationEstimate(padding_cells=8),
).run()
report = result.capacitance.truncation_estimate
print(report.max_relative_delta, report.richardson_matrix)

TruncationReport#

Result of a truncation estimate, stored in CapacitanceData.truncation_estimate.

ElectrostaticInitialCondition#

ElectrostaticInitialCondition.from_result(dc_result, *, tolerance=1e-3) -> ElectrostaticInitialCondition   # classmethod

Wraps an electrostatic result as an initial field for an FDTD run. Pass it to mw.Simulation.fdtd(..., initial_condition=ic). At prepare time, the FDTD solver sets its electric field to E = -grad(phi) on the Yee grid and leaves the magnetic field at zero. See Simulation.

Returns an ElectrostaticInitialCondition holding detached copies of phi, xc, yc, zc, epsilon_r, free_charge, cell_volume, conductor_mask, the field energy, the tolerance, and a provenance dict with the DC solve diagnostics. After the FDTD solver applies it, gauss_residual and gauss_residual_abs hold the measured residual, and result.electrostatic_prebias on the FDTD result reports the provenance.

The electrostatic cell centres must match the FDTD grid on every axis. Use the same Domain and GridSpec for both runs, and give the FDTD scene a boundary that does not extend the grid (for example BoundarySpec.periodic()); a PML boundary is rejected.

dc = mw.Simulation.electrostatic(dc_scene, boundary=boundary).run()
ic = mw.ElectrostaticInitialCondition.from_result(dc)
fdtd_scene = mw.Scene(domain=dc_scene.domain, grid=dc_scene.grid, boundary=mw.BoundarySpec.periodic())
result = mw.Simulation.fdtd(fdtd_scene, frequencies=[1e9], initial_condition=ic).run()
print(result.electrostatic_prebias["gauss_residual"])

Two lower-level methods are public: map_to_yee(prepared, *, dtype=torch.float64) returns the (Ex, Ey, Ez) Yee-edge fields for a prepared scene, and apply_to_solver(solver) writes them into an FDTD solver's field buffers. The FDTD runner calls them for you.