Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
df89520
Add TE10 wave ports, first-order ABC and S-parameter sweeps for Maxwell
Nov 5, 2026
2872585
Document wave ports, absorbing boundaries and sweeps
Nov 5, 2026
71321bb
Use the complex permittivity on absorbing faces and require a PEC por…
Nov 5, 2026
0aca6b3
Reject wave ports whose face is also PEC-constrained
Nov 5, 2026
c313425
Merge maxwell/1-core into maxwell/3-sweep-abc
Nov 5, 2026
b152bb3
Merge maxwell/1-core into maxwell/3-sweep-abc
Nov 5, 2026
675bbec
Merge maxwell/3-sweep-abc into maxwell/10-frontend-f2
Nov 6, 2026
b52e5be
Recognise the absorbing boundary, wave ports and sweeps in the Maxwel…
Nov 6, 2026
ca442fa
Reject facets that would carry two absorbing or port terms
Nov 6, 2026
00223b6
Merge maxwell/9-frontend-f1 into maxwell/10-frontend-f2 (PR workflow …
Nov 6, 2026
bd535a7
Merge forge/mwsync-9-frontend-f1 into maxwell/10-frontend-f2
Nov 10, 2026
cabdd93
Throw at exact port cutoff instead of returning NaN S-parameters
Nov 10, 2026
b9a2809
Merge forge/mwsync-9-frontend-f1 into forge/mwsync-10-frontend-f2
Nov 10, 2026
3dbdcd1
Merge forge/mwsync-9-frontend-f1 into forge/mwsync-10-frontend-f2
Nov 10, 2026
eb813f5
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 11, 2026
67e2f4c
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
5fdd3bf
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
9393413
Absorbing condition: scale-free row-space comparison
Nov 12, 2026
c0c25c6
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
0f400d1
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
32373f9
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
587a681
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
743daad
Absorbing condition: a term in E is rejected symbolically, independen…
Nov 12, 2026
5a8413a
Maxwell front end: reject a nu whose reciprocal is not representable …
Nov 12, 2026
0ed6f06
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
40d2e45
Wave ports: reject PEC on the interior of the port face
Nov 12, 2026
5a4505f
Maxwell front end: reject a reaction coefficient lost to underflow in…
Nov 12, 2026
4614d7c
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
819a8c0
Wave ports: state that the port needs real permittivity and zero cond…
Nov 12, 2026
6a7115b
Maxwell model: materialise the ports iterable once before validation
Nov 12, 2026
7482a1b
Wave ports: reject a complex permittivity at the port
Nov 12, 2026
7b123bc
Front end: materialise the ports keyword once before validation
Nov 12, 2026
548c6f8
Wave ports: restrict the power interpretation to propagating ports
Nov 12, 2026
ecb7a80
Tests: qualify propagation_constant in the axial power test
Nov 12, 2026
25b599d
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
a44e2f7
Wave ports and absorbing boundary: outgoing branch for lossless negat…
Nov 12, 2026
68d8d82
Front end: judge normal-dependent boundary factors at the actual normal
Nov 12, 2026
74015bf
Absorbing boundary: outgoing branch follows the sign of the frequency…
Nov 12, 2026
749e3ff
Absorbing boundary and wave ports: one outgoing rule for every sign o…
Nov 12, 2026
cb5014f
Wave ports: the operator path rejects negative frequencies only
Nov 12, 2026
af0312f
Wave ports: require positive real permittivity and positive permeability
Nov 12, 2026
a39574a
Wave ports: apply the TE10 admittance to the TE10 amplitude only
Nov 12, 2026
cb5d36a
Front end: judge boundary equations at the snapped actual normal, wit…
Nov 12, 2026
b7f2972
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 12, 2026
1575baa
Docstrings: the wave-port term is rank-one, and extra blocks are copi…
Nov 12, 2026
50279b2
Front end: judge vanishing boundary equations against their cancellat…
Nov 12, 2026
6f565c4
Comment: the port's modal boundary term and its sign
Nov 12, 2026
39b132d
Front end: zero entries by their own evaluation error, not by the siz…
Nov 13, 2026
5f243e5
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
2d23bda
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
e01f846
Front end: validate the trace arguments inside boundary derivatives
Nov 13, 2026
4fadb8d
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
c175b6a
Sweeps: an empty frequency collection gives an empty sweep
Nov 13, 2026
1ec43b6
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
276749a
Front end: classify boundary coefficients clearly zero, clearly nonze…
Nov 13, 2026
0413c3f
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
d1ee338
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
38594a2
Front end: classify boundary equations after the normal, and never in…
Nov 13, 2026
d665516
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
a14ea52
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
60630f3
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
165da59
Merge forge/mwsync-9-frontend-f1 into 10-frontend-f2
Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/src/boundary_conditions.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Restrictions of this release:
- Where two Dirichlet pieces of one field meet, the condition listed last in the `PDESystem` wins.
- Every field with a time derivative needs an initial condition, linear in that one field and finite at every node.
- Time-dependent mass or stiffness coefficients and `codegen = :mtk` are rejected.
- With `omega`, a time-domain curl-curl equation for a 3-component unknown in a Nédélec space becomes a frequency-domain `LinearProblem` (see `maxwell_model`); its only boundary condition is the perfect conductor `n × E = 0`, other pieces get `n × (ν curl E) = 0`, and its coefficients are real.
- With `omega`, a time-domain curl-curl equation for a 3-component unknown in a Nédélec space becomes a frequency-domain `LinearProblem` (see `maxwell_model`); its boundary conditions are the perfect conductor `n × E = 0` and the matched first-order absorbing condition `n × (ν curl E) = -sqrt(ε/μ) n × (n × ∂ₜE)` on lossless cells, wave ports are the `ports` keyword, other pieces get `n × (ν curl E) = 0`, and its coefficients are real.

"Time-dependent" means boundary data that varies with time, for every condition kind.

Expand Down
84 changes: 82 additions & 2 deletions docs/src/maxwell.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,45 @@ that is a function of `ω`, so a frequency sweep only recombines nonzero values
[`maxwell_operator!`](@ref), and further terms (boundary conditions, ports) are added as blocks with
`FiniteElementMethod.add_term!`.

## Wave ports, absorbing boundaries and frequency sweeps

Rectangular-waveguide ports and first-order absorbing boundaries are model keywords. A [`WavePort`](@ref)
on a planar boundary facet set launches and absorbs the TE10 mode of the rectangle it spans; `a_direction`
names the broad wall. Facet sets in `absorbing` get the first-order Silver-Müller condition
`n × (μr⁻¹ ∇ × E) = -i k0 sqrt(εc/μr) n × (n × E)` (`εc = εr - iσ/(ωε0)` of the adjacent material), exact for a plane wave at normal incidence (a TE10 wave
reflects `Γ = (β - k0)/(β + k0)` from it). [`solve_sweep`](@ref) returns the scattering matrix at each
angular frequency; it keeps one operator matrix and one factorisation pattern, and solves every port's
excitation from a single factorisation per frequency. The linear solver is the `solver` keyword (see
[`FiniteElementMethod.umfpack_solver`](@ref)).

```julia
using FiniteElementMethod, Ferrite
# A 50 mm section of WR-90 (22.86 mm × 10.16 mm), mesh in millimetres.
grid = generate_grid(Tetrahedron, (16, 7, 34), Vec(0.0, 0.0, 0.0), Vec(22.86, 10.16, 50.0))
ports = [WavePort("bottom"; a_direction = (1, 0, 0)), WavePort("top"; a_direction = (1, 0, 0))]
model = MaxwellModel(grid; pec = ["left", "right", "front", "back"], ports, length_scale = 1.0e-3)
sweep = solve_sweep(model, 2π .* (8.0e9:0.5e9:12.0e9))
sweep.S[2, 1, 5] # S21 at 10 GHz: |S21| ≈ 1, angle ≈ -93.3°
```

`Sᵢⱼ` is referred to the port faces, or to planes `deembed` mesh units inside them. Ports on different guides
are normalised through the TE10 wave impedance `ωμ0μr/β`. For a propagating port these are power waves. Below cutoff
the propagation constant is `β = -iα`, the evanescent branch, which carries no real axial power: the coefficients
are then generalized traveling-wave coefficients with the same normalisation, still supported, but without an
individual incident or outgoing power, and `S` is not power conserving.

A wave port is a single-mode TE10 termination: its admittance acts on the TE10 amplitude of the trace only (a rank-one
term that couples all the dofs of the port face), and the evanescent higher modes see the natural (magnetic-wall)
boundary at the port plane, so they are reflected, not absorbed, and a lossless single-mode structure conserves
power. Keep about one decay length `1 / sqrt(kc² - k²)` of the first evanescent mode (`kc = 2π/a` for TE20, `π/b` for
TE01) of uniform lead between a discontinuity and the port, otherwise `S` depends on the lead length. Wave ports need positive frequencies; a
zero or negative `ω` is rejected, since a real system has `S(-ω) = conj(S(ω))`.

A port must lie in an ordinary passive material: a complex `eps_r`, a nonzero conductivity, a non-positive `eps_r`
or a non-positive `mu_r` at a port is rejected, because the power-wave normalisation above holds for a real wave
impedance and the outward power of the TE10 mode is `Re(β/μr) > 0` only for positive `μr` and `εr`. Put loss behind
the port, not in its face.

## From a PDESystem

`FEMDiscretization(Ω, t; omega, spaces = Dict(E => Nedelec{RefTetrahedron, 1}()))` discretizes the
Expand All @@ -39,7 +78,7 @@ for the equivalent `MaxwellModel` (in units with `ε0 = μ0 = 1`). The operator
and the perfect conductor with [`facet_normal`](@ref).

```julia
using FiniteElementMethod, Ferrite, ModelingToolkit, LinearAlgebra, LinearSolve
using FiniteElementMethod, Ferrite, ModelingToolkit, DomainSets, LinearAlgebra, LinearSolve
grid = generate_grid(Tetrahedron, (8, 8, 8), Vec(0.0, 0.0, 0.0), Vec(1.0, 1.0, 1.0))
Ω = MeshDomain(grid)
@parameters x y z t
Expand All @@ -56,7 +95,38 @@ field_values(MaxwellSolution(model, omega, sol.u), [Vec(0.5, 0.5, 0.5)]).E
```

Coefficients are real, so a complex permittivity `ε' - iε''` is only available on the operator-level
`MaxwellModel`. Absorbing boundaries and ports are not yet part of the `PDESystem` path.
`MaxwellModel`.

### Absorbing boundaries, ports and sweeps

The first-order absorbing condition is written in its time-domain form,
`n × (ν ∇ × E) = -sqrt(ε/μ) n × (n × ∂ₜE)` with `ε = a₂` and `ν = 1/μ` of the cells next to the piece. With
`∂ₜ = iω` and `ε0 = μ0 = 1` this is the model's `n × (μr⁻¹ ∇ × E) = -i k0 sqrt(εr/μr) n × (n × E)`, so the
piece goes to `absorbing`. Any equivalent set of equations is accepted; at the actual normal of every facet the
conditions must span exactly the two tangential equations of this one, and a different coefficient of
`curl E`, a different impedance, the opposite sign or an added term is an error. The cells next to the piece
must be lossless (`a₁ = a₀ = 0`); a lossy one has no time-domain form here and needs `MaxwellModel`'s
`absorbing` keyword.

A [`WavePort`](@ref) is modal data rather than a local condition, so ports are the `ports` keyword of
`FEMDiscretization`, on pieces without a condition in the `PDESystem`. `discretize` treats them as matched
terminations of the source problem; `solve_sweep(pdesys, disc, omegas)` drives them and returns the scattering
matrices, as `solve_sweep(maxwell_model(pdesys, disc).model, omegas)` does. With ports `a₀` must be zero, so
that the model does not depend on `omega`, and a sweep rejects a volume source.

```julia
grid = generate_grid(Tetrahedron, (12, 6, 15), Vec(0.0, 0.0, 0.0), Vec(22.86, 10.16, 30.0)) # WR-90, mm
Ω = MeshDomain(grid)
n, Eb = facet_normal(boundarypiece(Ω, :top)), [E(t, boundarypiece(Ω, :top))[c] for c in 1:3]
abc = cross(n, curl(Eb, X)) .~ -cross(n, cross(n, Dt.(Eb)))
pec = reduce(vcat, [cross(facet_normal(Γ), [E(t, Γ)[c] for c in 1:3]) .~ 0 for Γ in boundarypiece.(Ref(Ω), [:left, :right, :front, :back])])
eqs = [curl(curl(Ev, X), X)[c] + Dt(Dt(Ev[c])) ~ 0 for c in 1:3]
@named sys = PDESystem(eqs, [pec; abc], [t ∈ Interval(0.0, 1.0), (x, y, z) ∈ Ω], [t, x, y, z], [E(t, x, y, z)])
k0 = 2π * 10.0e9 / FiniteElementMethod.C0 * 1.0e-3 # 10 GHz in rad/mm
ports = [WavePort(boundarypiece(Ω, :bottom); a_direction = (1, 0, 0))]
disc = FEMDiscretization(Ω, t; omega = k0, spaces = Dict(E => Nedelec{RefTetrahedron, 1}()), ports)
solve_sweep(sys, disc, k0 .* [0.8, 1.0, 1.2]).S # |S11| ≈ 0.14 at 10 GHz, the reflection of the absorbing end
```

```@docs
curl(::AbstractVector, ::NTuple{3, Any})
Expand All @@ -83,6 +153,16 @@ MaxwellSolution
field_values
FiniteElementMethod.maxwell_rhs
FiniteElementMethod.add_term!
WavePort
FiniteElementMethod.WavePortData
solve_sweep
MaxwellSweep
FiniteElementMethod.umfpack_solver
FiniteElementMethod.tangential_mass
FiniteElementMethod.port_excitations
FiniteElementMethod.s_parameters
FiniteElementMethod.propagation_constant
FiniteElementMethod.cutoff_frequency
FiniteElementMethod.EPS0
FiniteElementMethod.MU0
FiniteElementMethod.C0
Expand Down
7 changes: 5 additions & 2 deletions src/FiniteElementMethod.jl
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ using DiffEqBase: BrownFullBasicInit
using DomainSets: DomainSets
using Ferrite: Ferrite, Lagrange, RefLine, RefTriangle, RefQuadrilateral, RefTetrahedron, RefHexahedron, curl
using ForwardDiff: ForwardDiff
using LinearAlgebra: dot, mul!, norm, rank
using LinearAlgebra: cross, dot, lu, lu!, mul!, norm, normalize, rank, svd
using ModelingToolkit: ModelingToolkit, @parameters, @variables, Differential, MTKParameters,
ProblemTypeCtx, System, complete, getmetadata
using NonlinearSolveFirstOrder: NewtonRaphson
Expand All @@ -22,7 +22,7 @@ using PrecompileTools: PrecompileTools
using RuntimeGeneratedFunctions: RuntimeGeneratedFunctions
using SciMLBase: SciMLBase, DAEFunction, DAEProblem
using SciMLBase.SymbolicIndexingInterface: SymbolicIndexingInterface, getp, parameter_index, variable_index
using SparseArrays: SparseMatrixCSC, nnz, nonzeros, nzrange, rowvals
using SparseArrays: SparseMatrixCSC, findnz, nnz, nonzeros, nzrange, rowvals, sparse
using SymbolicUtils: SymbolicUtils
using Symbolics: Symbolics, Equation, Num, @register_array_symbolic, substitute, unwrap

Expand All @@ -43,6 +43,7 @@ export FieldInfo, FEMMetadata, piece_nodes, normal_flux, write_vtk, facet_dofs,
export Lagrange, RefLine, RefTriangle, RefQuadrilateral, RefTetrahedron, RefHexahedron

using PDEBase: StrongForm, MeshDomain, Region, boundarypiece, boundarypieces, NormalDerivative
include("maxwell/ports.jl") # before the discretization, which holds WavePorts
using PDEBase.StrongForm: Weighted
include("discretization.jl")
include("frontend.jl")
Expand All @@ -56,9 +57,11 @@ export Weighted
# from a PDESystem without the scalar weak form.
include("maxwell/model.jl")
include("maxwell/driven.jl")
include("maxwell/sweep.jl")
include("maxwell/frontend.jl")
export MaxwellMaterial, MaxwellModel, MaxwellTerm, maxwell_operator, maxwell_operator!
export MaxwellSolution, driven_problem, solve_driven, field_values
export WavePort, MaxwellSweep, solve_sweep
export curl, facet_normal, maxwell_model

include("precompile.jl")
Expand Down
17 changes: 13 additions & 4 deletions src/discretization.jl
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ PDEBase.contains_point(grid::Ferrite.Grid, x) = _contains_point(grid, x)
FEMDiscretization(Ω::MeshDomain, t = nothing; spaces = Dict(), regions = Dict(),
quadrature = nothing, test_space = Galerkin(), ibp = Dict(), pairing = Dict(),
codegen = :numeric, dirichlet = :algebraic, algebraic_abstol = :auto, natural = (), boundary_check = :warn,
omega = nothing, kwargs...)
omega = nothing, ports = [], kwargs...)

Finite-element discretization of a `PDESystem` whose spatial domain is the mesh domain `Ω`
(of a `Ferrite.Grid`), with time variable `t`. `discretize(pdesys, disc)` assembles the
Expand Down Expand Up @@ -81,6 +81,9 @@ gives a `PDENoTimeSolution`.
see [`maxwell_model`](@ref) for the equations it accepts. `omega` must be positive and finite and
needs the time variable `t`, which the `PDESystem` is written in; `test_space`, `regions`, `ibp` and
`pairing` do not apply to it and must keep their defaults. A Nédélec space needs `omega`.
- `ports`: [`WavePort`](@ref)s of the frequency-domain Maxwell path (with `omega`), on boundary pieces that
have no condition in the `PDESystem`; [`solve_sweep`](@ref) drives them, and `discretize` treats them as
matched terminations.
- `codegen = :mtk` is reserved and raises; remaining keywords are
passed to the `DAEProblem` (or the steady `NonlinearProblem`), where a keyword given at the
`discretize` call wins. `iv`, `unknowns`, `du0`, `coordinate`, `name` and `parameters` are set
Expand Down Expand Up @@ -118,6 +121,7 @@ struct FEMDiscretization{T} <: PDEBase.AbstractMeshDiscretization
boundary_check::Symbol
algebraic_abstol::Union{Symbol, Nothing, Float64}
omega::Union{Nothing, Float64}
ports::Vector{WavePort}
kwargs::NamedTuple
end

Expand Down Expand Up @@ -151,7 +155,7 @@ function FEMDiscretization(
domain::PDEBase.MeshDomain, time = nothing; spaces = Dict(), regions = Dict(), quadrature = nothing,
test_space = Galerkin(), ibp = Dict(), pairing = Dict(), codegen::Symbol = :numeric,
dirichlet::Symbol = :algebraic, algebraic_abstol = :auto, natural = (), boundary_check::Symbol = :warn,
omega = nothing, kwargs...
omega = nothing, ports = WavePort[], kwargs...
)
domain.mesh isa Ferrite.Grid ||
throw(ArgumentError("FEMDiscretization needs a MeshDomain of a Ferrite.Grid, got a mesh of type $(typeof(domain.mesh))"))
Expand All @@ -178,12 +182,17 @@ function FEMDiscretization(
)
_check_reserved(kwargs)
_check_omega(omega, time, spaces, test_space, regions, ibp, pairing)
ports = collect(ports)
all(p -> p isa WavePort, ports) ||
throw(ArgumentError("ports must be WavePorts, as ports = [WavePort(Γ; a_direction = (1, 0, 0))]; got $(repr(ports))"))
omega === nothing && !isempty(ports) &&
throw(ArgumentError("ports belong to the frequency-domain Maxwell path; give the angular frequency omega"))
return FEMDiscretization{typeof(time)}(
domain, time, Dict{Any, Ferrite.Interpolation}(_field_op(k) => ip for (k, ip) in spaces),
Dict{Any, Any}(_field_op(k) => r for (k, r) in regions),
quadrature, test_space, Dict{Any, StrongForm.IBPPolicy}(ibp), Dict{Equation, Any}(pairing),
codegen, dirichlet, unique(natural), boundary_check, algebraic_abstol isa Real ? Float64(algebraic_abstol) : algebraic_abstol,
omega === nothing ? nothing : Float64(omega), NamedTuple(kwargs)
omega === nothing ? nothing : Float64(omega), WavePort[ports...], NamedTuple(kwargs)
)
end

Expand Down Expand Up @@ -239,6 +248,6 @@ PDEBase.supported_conditions(::FEMDiscretization) = PDEBase.SupportedConditions(
- Where two Dirichlet pieces of one field meet, the condition listed last in the `PDESystem` wins.
- Every field with a time derivative needs an initial condition, linear in that one field and finite at every node.
- Time-dependent mass or stiffness coefficients and `codegen = :mtk` are rejected.
- With `omega`, a time-domain curl-curl equation for a 3-component unknown in a Nédélec space becomes a frequency-domain `LinearProblem` (see `maxwell_model`); its only boundary condition is the perfect conductor `n × E = 0`, other pieces get `n × (ν curl E) = 0`, and its coefficients are real.
- With `omega`, a time-domain curl-curl equation for a 3-component unknown in a Nédélec space becomes a frequency-domain `LinearProblem` (see `maxwell_model`); its boundary conditions are the perfect conductor `n × E = 0` and the matched first-order absorbing condition `n × (ν curl E) = -sqrt(ε/μ) n × (n × ∂ₜE)` on lossless cells, wave ports are the `ports` keyword, other pieces get `n × (ν curl E) = 0`, and its coefficients are real.
"""
)
Loading
Loading