Modal and Terminal Wave-Port Validation

1. Goal

This project defines a reproducible benchmark suite for RF and microwave wave ports. It validates two related but different formulations:

• Modal wave ports represent the eigenmodes of a cross-section. They are the natural benchmark basis for hollow metallic guides, dielectric guides, substrate-integrated guides, and other structures described by TE, TM, or hybrid modes.
• Terminal wave ports represent voltages and currents on distinct signal and reference conductors. They are the natural benchmark basis for coaxial, planar, balanced, differential, and multiconductor transmission lines.

Every example has two independently organized stages:

1. 2D_Mode validates the cross-section, mesh, port definition, mode identity, cutoff behavior, impedance, and propagation quantities.
2. 3D_Sparam extrudes the accepted cross-section into a uniform fixture and compares only the complete complex S-matrix.

Each stage has its own Convergence_study and Comparison directories. Convergence exploration must not be hidden inside the primary comparison scripts.

Important

This repository currently defines the benchmark architecture and templates. It does not yet contain validated example results. A result is not a standard merely because a solver completed; its reference source, confidence, convergence, conventions, inputs, and version must all be recorded.

2. Frequency scope: 0 Hz to 300 GHz

The project envelope is the interval from the quasi-static limit through 300 GHz. This does not mean that one geometry, one port, or one simulation must cover the whole interval.

• Store 0 Hz only as an analytical or quasi-static limit. Power-wave S-parameters and time-domain excitations use a finite positive lower frequency.
• Give every example its own validated frequency band.
• For a cutoff mode, distinguish below-cutoff, cutoff-guard, and propagating regions.
• For a TEM or quasi-TEM fundamental mode, record fundamental_cutoff: none and bound the high-frequency range using the first higher-order mode, radiation/leakage, dispersion, and material-model validity.
• Use multiple scaled examples to cover the project envelope. Standard rectangular waveguide alone requires different guide sizes as frequency changes.
• Above 110 GHz, dimensional tolerance, surface roughness, conductivity, dielectric dispersion, connector/interface definitions, and reference-plane uncertainty become increasingly important and must be preserved in the example provenance.

A useful planning split is:

Project region	Primary benchmark emphasis
Quasi-static limit to 1 GHz	Coaxial, parallel-plate, stripline, twin-lead, and other terminal lines
1–30 GHz	Terminal lines plus classical hollow and substrate-integrated guides
30–110 GHz	Millimeter-wave hollow, dielectric, integrated, and planar guides
110–300 GHz	Scaled metallic guides, on-wafer planar lines, dielectric guides, and fabrication-sensitive structures

These are organizational regions, not universal operating limits.

3. Port selection

Choose the benchmark basis from the conductor topology and the desired network definition.

Cross-section	Preferred benchmark port	Fundamental behavior
Closed hollow guide without signal/reference terminals	Modal	TE/TM modes with cutoff
Open or closed dielectric guide without circuit terminals	Modal	TE/TM/hybrid modes; cutoff depends on the family
SIW or related TE-like integrated guide	Modal	TE-like modes with cutoff
Inner conductor enclosed by an outer reference conductor	Terminal	TEM fundamental; higher-order cutoff
Signal conductor referenced to one or more ground conductors	Terminal	TEM/quasi-TEM fundamental; higher-order cutoff
Balanced or multiconductor line	Terminal	Common, differential, and coupled terminal bases
Ambiguous or discontinuous cross-section	Review required	Move the plane or justify the basis

A modal solver can mathematically solve modes of many multiconductor lines. That does not make its raw modal S-matrix identical to a terminal S-matrix. Compare modal and terminal results only after matching:

• port reference planes and de-embedding;
• time-harmonic and traveling-wave conventions;
• reference impedance and power normalization;
• channel ordering and mode count;
• an explicit modal-to-terminal basis transformation, when required.

Never force a terminal port onto a hollow TE/TM guide that has no defensible signal and reference terminals.

4. Per-example architecture

Group examples first by port family and then by physical structure:

examples/
├── Modal_Wave_Port/
│   └── {example}/
└── Terminal_Wave_Port/
    └── {example}/

Every {example} uses this structure:

{example}/
├── README.md
├── 2D_Mode/
│   ├── Convergence_study/
│   │   ├── Mesh.md
│   │   ├── Port.md
│   │   ├── Frequency_Sweep.md
│   │   └── Recommended_Setup.yaml
│   └── Comparison/
│       ├── Mode_Simulation.py
│       ├── Standard_Mode_Results.py
│       ├── Comparison_plot.py
│       └── Results/
│           ├── manifest.json
│           ├── simulated_modes.csv
│           ├── standard_modes.csv
│           └── comparison_metrics.csv
└── 3D_Sparam/
    ├── Convergence_study/
    │   ├── Mesh.md
    │   ├── Port.md
    │   ├── Domain.md
    │   ├── Runtime.md
    │   ├── Line_Length.md
    │   └── Recommended_Setup.yaml
    └── Comparison/
        ├── SMatrix_Simulation.py
        ├── Standard_SMatrix_Results.py
        ├── Comparison.py
        └── Results/
            ├── manifest.json
            ├── simulated.sNp
            ├── standard.sNp
            └── comparison_metrics.csv

Use examples/_template as the copyable starting point.

4.1 2D_Mode responsibilities

2D_Mode/Convergence_study determines the recommended 2D setup:

• Mesh.md studies transverse grid resolution, conductor/gap resolution, and numerical stability of complex mode quantities.
• Port.md studies port extent, boundary connectivity, integration paths, mode count, polarization, and mode sorting/tracking.
• Frequency_Sweep.md studies frequency sampling, cutoff localization, mode crossings, and field-overlap tracking.
• Recommended_Setup.yaml contains only values accepted by those studies.

2D_Mode/Comparison keeps three responsibilities separate:

• Mode_Simulation.py builds and runs the candidate 2D mode solver using Recommended_Setup.yaml.
• Standard_Mode_Results.py generates or loads the independent standard mode results and their confidence metadata.
• Comparison_plot.py aligns the two datasets, applies validity masks, computes errors, and generates comparison plots.

Mode_Simulation.py must never silently generate the standard against which it is judged.

4.2 3D_Sparam responsibilities

3D_Sparam/Convergence_study determines the recommended 3D setup:

• Mesh.md studies the 3D spatial grid and local feature refinements.
• Port.md studies port-plane inset, port extent, channel count, normalization, reference planes, and de-embedding.
• Domain.md studies transverse padding and absorber/PML distance.
• Runtime.md studies source bandwidth, run time, shutoff, and energy decay.
• Line_Length.md studies whether the fixture length gives resolvable phase and attenuation without unnecessary numerical loss or cost.
• Recommended_Setup.yaml contains only values accepted by those studies.

3D_Sparam/Comparison also separates three responsibilities:

• SMatrix_Simulation.py builds and runs the candidate uniform 3D fixture.
• Standard_SMatrix_Results.py generates or loads the independent standard complex S-matrix and its confidence metadata.
• Comparison.py aligns reference planes, conventions, impedances, frequency samples, and bases before computing comparison metrics.

The 3D release benchmark compares S-parameters only. Three-dimensional field monitors may be used for debugging but are not part of the standard comparison.

5. Standard-result sources and confidence

The word standard means the comparison reference, not necessarily an international standard. Every standard dataset must record:

• reference_method;
• confidence;
• source title, URL, DOI, or report number;
• equations or source-code repository and exact commit;
• software version and input-file hashes;
• geometry, material, boundary, mesh, and frequency assumptions;
• units, time convention, impedance normalization, and reference planes;
• convergence evidence;
• license and redistribution status;
• the code path that created the committed standard table.

5.1 Confidence hierarchy

Reference method	Default confidence	Requirements
Exact analytical solution	High	The implemented equations are exact for the modeled assumptions, limiting cases are tested, and units/conventions are explicit
Reliable open-source solver	Medium	The code is publicly auditable, version/commit and inputs are pinned, convergence is demonstrated, and at least one relevant published paper is cited
CST or Ansys HFSS	Medium	The complete model/export, solver version, mesh convergence, port basis, normalization, and reference planes are available
Other commercial software	Low	Lower confidence by default; preserve the same provenance fields and do not promote screenshots or plots to numerical standards

Confidence belongs to a specific dataset, not to a product name. Downgrade or reject a reference when its assumptions, inputs, mesh, convergence, reference planes, or complex convention are missing.

5.2 Analytical solution — high confidence

Use an analytical standard whenever the modeled geometry and materials satisfy its assumptions. Typical examples include:

• PEC rectangular and circular waveguide cutoff and propagation constants;
• ideal coaxial and parallel-plate TEM impedance and propagation;
• ideal homogeneous stripline or twin-lead limits;
• dielectric slab characteristic equations;
• the uniform matched-line relation (S_{21}=S_{12}=e^{-\gamma L}) with (S_{11}=S_{22}=0), after convention and reference-plane alignment.

An approximation is not promoted to high confidence merely because it is a closed-form expression. Mark conformal-mapping, quasi-static, empirical, and curve-fit formulas with their approximation range.

5.3 Reliable open-source code — medium confidence

Use a reliable open-source solver when no exact solution exists or when the benchmark includes loss, dispersion, periodicity, or complex geometry.

Candidate tools include:

• openEMS for FDTD S-parameter references;
• MPB for eigenmodes and dispersion of dielectric or periodic guides;
• Meep for time-domain propagation and mode decomposition;
• another open solver only after its formulation, tests, license, and maintenance status are reviewed.

For every open-source standard:

1. Pin the exact release and commit.
2. Commit or hash the complete input.
3. Run an independent mesh/domain/runtime convergence study.
4. Preserve the raw complex numerical output.
5. Cite at least one paper relevant to the solver method and one paper relevant to the physical waveguide example whenever available.
6. Explain any conversion from the solver's native convention.

A digitized plot without reproducible input remains low confidence.

5.4 Commercial software

CST and HFSS data are medium confidence only when they are reproducible. Required evidence includes:

• exact software/version and solver type;
• native project or a complete parameterized reconstruction;
• adaptive-mesh or refinement history;
• material models and units;
• port geometry, mode/terminal ordering, impedance, and renormalization;
• reference planes and de-embedding;
• raw complex CSV or Touchstone export;
• frequency interpolation policy.

A screenshot, manually copied curve, or undocumented Touchstone file is low confidence. Results from other commercial tools are low confidence by default.

5.5 Conflict policy

When references disagree:

1. verify geometry, units, materials, conventions, and reference planes;
2. compare each source only inside its documented validity range;
3. rerun convergence independently;
4. retain all conflicting datasets and explain the decision;
5. never average incompatible results to manufacture a standard.

If no defensible standard exists, label the example reference_pending instead of assigning a pass/fail result.

6. Typical waveguide catalog for 0–300 GHz

This chapter is the initial catalog, not a declaration that every policy is already validated. Each family will receive its own example README, references, dimensions, material range, cutoff table, and convergence evidence later.

6.1 Modal wave-port examples

These examples are compared in a modal TE/TM/hybrid basis.

Family	Typical mode behavior	Cutoff and reference strategy	0–300 GHz relevance
Rectangular PEC waveguide	Dominant TE10 with higher TE/TM modes	Exact analytical cutoff, propagation, and impedance for the ideal guide	Core benchmark from microwave through 300 GHz using scaled standard guide sizes
Circular PEC waveguide	Dominant degenerate TE11 pair; TE/TM hierarchy	Exact Bessel-root cutoff; explicitly track polarization and degeneracy	Common feed, antenna, and metrology guide
Elliptical metallic waveguide	TE/TM-like modes described with elliptical coordinates	Analytical/semi-analytical characteristic equations plus numerical validation	Useful degeneracy-breaking extension of circular guide
Single- and double-ridged waveguide	Lower dominant cutoff and wider single-mode range than an equivalent hollow guide	Numerical standard plus published paper; analytical approximations are secondary	Broadband microwave and millimeter-wave benchmark
Dielectric-loaded metallic waveguide	TE/TM or hybrid modes altered by the dielectric loading	Exact result only for special symmetric cases; otherwise converged numerical reference	Tests material interfaces, dispersion, and mode tracking
Substrate-integrated waveguide (SIW)	TE-like mode confined by top/bottom metal and via fences	Approximate equivalent-width formulas plus converged full-wave reference	Important planar microwave/mmWave guide
Half-mode, ridged, folded, or empty SIW	Modified TE-like or hybrid SIW modes	Converged open-source/commercial result and a relevant paper	Advanced integrated-guide coverage
Dielectric slab waveguide	TE/TM families; the ideal fundamental slab mode may have no cutoff	Exact characteristic equation for ideal isotropic layers	Clean dielectric-interface and open-boundary benchmark
Circular dielectric rod	Hybrid HE/EH modes; fundamental behavior depends on materials and boundary model	Characteristic equation for ideal rods, otherwise numerical	Low-loss millimeter-wave guide
Rectangular dielectric rod	Hybrid modes with no simple general closed form	Converged eigenmode reference plus paper	Fabrication-friendly dielectric guide
Image guide and NRD guide	Dielectric mode confined by one or two conducting planes	Special-case theory plus converged eigenmode reference	Classical millimeter-wave dielectric guides
Goubau or single-conductor surface-wave line	Bound surface mode without a separate circuit reference terminal	Modal eigenmode reference and field-containment checks	Tests open, slowly decaying surface modes
Ridge/groove gap waveguide	Bandgap-confined quasi-TE or hybrid propagation	Dispersion/eigenmode calculation plus finite 3D reference	Contactless millimeter-wave interconnect family
Corrugated, spoof-plasmon, and periodic slow-wave guide	Dispersive Bloch/surface modes and stopbands	Unit-cell dispersion plus finite-length S-matrix; no universal cutoff formula	Advanced broadband/slow-wave coverage

Special cautions:

• A modal port row/column represents a port-mode pair, so the matrix dimension changes when the requested channel set changes.
• Circular and square guides can contain degenerate modes whose orientation is not determined by mode index alone.
• Dielectric and surface guides need a port-domain convergence study because their fields extend into open space.
• Periodic guides need both unit-cell dispersion and finite-length S-parameter validation.

6.2 Terminal wave-port examples

These examples are compared in a conductor-terminal basis. Differential and common-mode channels are derived only after confirming terminal labels.

Family	Typical mode behavior	Cutoff and reference strategy	0–300 GHz relevance
Circular coaxial line	Exact TEM fundamental with no low-frequency cutoff	Exact impedance/propagation for the ideal line; calculate first TE/TM higher-order cutoff	Primary near-DC-to-mmWave terminal benchmark
Rectangular or square coaxial line	TEM fundamental with higher-order modes	Analytical/conformal result where valid, otherwise converged numerical reference	Tests noncircular closed terminal geometry
Parallel-plate line	TEM fundamental plus higher-order TE/TM modes	Exact ideal TEM result; finite-width fringing requires numerical validation	Simplest two-terminal benchmark
Twin-lead/two-wire line	Balanced TEM/quasi-TEM open mode	Exact or quasi-static homogeneous-medium reference plus domain convergence	Balanced-line benchmark
Microstrip	Dispersive quasi-TEM fundamental with no strict geometric cutoff	Quasi-static formulas are approximate; use a converged solver/paper for broadband standard	Core planar line from RF through mmWave
Centered or offset stripline	TEM in an ideal homogeneous dielectric; asymmetry changes impedance	Analytical/quasi-static reference for ideal cases, numerical reference otherwise	Shielded planar benchmark
Open CPW	Quasi-TEM signal-to-coplanar-ground mode	Conformal/quasi-static formulas plus open-domain numerical convergence	On-wafer and broadband planar benchmark
Grounded CPW	Quasi-TEM mode with side grounds and a separate reference plane	Converged numerical reference; check reference connectivity and via fences	PCB and on-wafer benchmark
Slotline and coplanar strip	Balanced/odd quasi-TEM slot modes	Analytical approximation plus converged numerical standard	Complements CPW with different terminal symmetry
Suspended stripline and inverted microstrip	Quasi-TEM mode with increased air-field fraction	Numerical/paper standard and domain convergence	Low-loss microwave/mmWave planar guides
Edge-coupled microstrip	Coupled even/odd terminal modes	Multiconductor quasi-TEM or numerical reference; transform to common/differential basis explicitly	Coupled-line and differential benchmark
Differential stripline	Differential and common terminal modes	Multiconductor reference with exact terminal ordering and mixed-mode transform	High-speed and RF differential interconnect
Multiconductor CPW	Coupled terminal modes and non-diagonal impedance matrix	Converged terminal-basis reference	Tests matrix impedance and basis transforms
Substrate-integrated coaxial line	TEM-like signal conductor enclosed by via/plane reference	Numerical reference plus higher-order cutoff study	Integrated closed terminal guide
Finline or antipodal finline	Hybrid/slot-like propagation	Use a terminal benchmark only when signal/reference conductors and paths are unambiguous; otherwise classify as modal	Conditional mmWave transition/guide example

Special cautions:

• “No fundamental cutoff” does not mean “simulate exactly at 0 Hz.”
• Open lines need sufficient port extent and domain padding for field decay.
• A TerminalWavePort requires a defensible voltage/current definition that does not intersect unintended metal.
• The first higher-order mode, radiation onset, substrate mode, connector limit, or material-model limit sets the upper benchmark frequency.
• Coupled structures require a documented single-ended-to-mixed-mode transformation before matrix comparison.

6.3 Initial implementation order

Implement the catalog in increasing order of ambiguity:

1. rectangular PEC waveguide;
2. circular PEC waveguide;
3. circular coaxial line;
4. parallel-plate line;
5. ideal stripline;
6. microstrip;
7. open and grounded CPW;
8. dielectric slab;
9. dielectric rod and SIW;
10. ridged, gap, periodic, and multiconductor families.

This order establishes exact analytical gates before introducing open boundaries, dispersion, degeneracy, periodicity, and coupled terminal bases.

7. 2D mode workflow

7.1 Build and inspect

1. Construct the canonical cross-section in explicit units.
2. Assign conductors, dielectrics, background, and boundaries.
3. Place the port plane in a straight, locally uniform section.
4. Plot materials, conductors, boundaries, integration paths, and propagation direction from the exact solver inputs.
5. Load only the accepted settings from 2D_Mode/Convergence_study/Recommended_Setup.yaml.

7.2 Solve and record

For every requested frequency and channel, record:

• complex effective index (n_\mathrm{eff});
• effective permittivity when physically meaningful;
• propagation constant (\gamma=\alpha+j\beta) under the documented convention;
• field wave impedance for TE/TM modes;
• terminal characteristic-impedance matrix for terminal modes;
• normalized 2D electric and magnetic fields;
• mode label, polarization/symmetry, sorting rule, and overlap with the prior frequency.

Do not store field wave impedance and terminal characteristic impedance in one ambiguous impedance column.

Track modes by field overlap and physical symmetry, not only by solver index.

7.3 Compare

Comparison_plot.py must:

1. load candidate and standard tables independently;
2. verify compatible units and conventions;
3. match modes by label, symmetry, and field overlap;
4. apply cutoff and confidence masks;
5. compute complex and scalar errors;
6. plot candidate, standard, difference, and validity region;
7. write machine-readable metrics and a manifest.

8. Cutoff-frequency policy

8.1 Modes with cutoff

For every TE/TM or higher-order mode:

1. calculate analytical cutoff when available;

2. estimate numerical cutoff from the solved propagation behavior;

3. record both and their relative difference;

4. divide the sweep into:

   • below cutoff: (f < 0.95f_c);
   • cutoff guard band: (0.95f_c \le f \le 1.05f_c);
   • propagating band: (f > 1.05f_c).

The five-percent guard is a default. Widen it when reference uncertainty, dispersion, degeneracy, or numerical sensitivity requires more margin.

Below cutoff, the mode is evanescent. In the guard band, impedance, normalization, group velocity, mode ordering, and finite-run accuracy can be highly sensitive. Therefore:

• show below-cutoff and guard-band results, but exclude them from the default propagating S-parameter gate;
• use a separate evanescent reference if below-cutoff transmission is an intended benchmark;
• split a sweep at each higher-order cutoff when the propagating matrix dimension changes;
• never compare matrices of different dimensions solely because their frequency coordinates match.

8.2 Modes without fundamental cutoff

Record fundamental_cutoff: none, select a finite positive lower frequency, and report the first higher-order cutoff or other upper-band limit. A quasi-TEM line may still become dispersive, radiative, leaky, or multimode.

9. 3D S-parameter workflow

9.1 Construct a uniform fixture

1. Extrude the accepted 2D cross-section by length (L).
2. Place equivalent ports at uniform cross-sections on both ends.
3. Use compatible channel definitions, materials, and frequency samples.
4. record both reference planes and every de-embedding distance/sign.
5. load only the accepted settings from 3D_Sparam/Convergence_study/Recommended_Setup.yaml.

Choose (L) long enough to resolve propagation phase and attenuation, but not so long that numerical loss and cost dominate. For a matched uniform single-mode line, the analytical standard is approximately (S_{11}=S_{22}=0) and (S_{21}=S_{12}=e^{-\gamma L}) after convention and reference-plane alignment.

9.2 Compare the full complex S-matrix

Before comparison, verify the same:

• frequency samples;
• port reference planes and de-embedding;
• time and traveling-wave convention;
• reference impedance and renormalization;
• channel ordering and count;
• modal, terminal, single-ended, or mixed-mode basis.

Save and compare:

• linear magnitude and dB magnitude;
• unwrapped phase where the magnitude is above the numerical noise floor;
• insertion and return loss;
• complex residual (S_{ij}^{test}-S_{ij}^{standard});
• reciprocity error for reciprocal fixtures;
• passivity error for passive fixtures.

Do not gate the phase of a nearly zero reflection coefficient. Use absolute linear reflection or complex residual instead.

Keep three errors separate:

1. standard accuracy: candidate versus the independent standard;
2. port-formulation difference: compatible modal versus terminal results after basis conversion;
3. numerical convergence: accepted setup versus extra-refined setup.

Agreement between two candidate solvers or two port formulations is not proof that either is correct.

10. Convergence policy

Each convergence file changes one setup family at a time. Keep the physical geometry, materials, comparison convention, and all unrelated settings fixed.

Every study must record:

• coarse, nominal, and extra-refined variants;
• exact changed values;
• mode or S-matrix comparison over the valid frequency mask;
• worst channel and frequency;
• mesh/cell count, runtime, and estimated or actual cost;
• failed, divergent, or incomplete variants;
• selected setting and engineering justification;
• input and result hashes.

For 3D S-parameters, the suggested setup-convergence target is accepted versus extra-refined agreement within 0.2 dB magnitude and 5° phase over the declared propagating passband. Each example may tighten or replace these values with justification.

The convergence documents write their accepted settings to the stage-specific Recommended_Setup.yaml. Primary comparison scripts read that file and do not contain hidden convergence loops.

11. Result manifest

Every 2D and 3D result directory must contain a manifest with:

• example and port-family name;
• input and geometry hashes;
• solver, adapter, package, and reference-code versions;
• geometry/material provenance;
• standard method and confidence;
• paper citations and code commit where applicable;
• requested/detected channel labels;
• cutoff values and validity masks;
• port geometry, direction, basis, impedance, and reference planes;
• mesh statistics and convergence source files;
• runtime and termination reason;
• complex convention and every conjugation, renormalization, de-embedding, or basis transformation;
• acceptance thresholds and metrics;
• remote task identifiers, logs, and cost when applicable.

Never start a paid cloud run merely because a model serializes. Inspect the 2D ports and 3D model locally, record the exact model hash and estimate, and obtain explicit approval for that model before submission.

12. Per-example checklist

• The example is placed under Modal_Wave_Port or Terminal_Wave_Port with a stated physical reason.
• Geometry, materials, units, boundaries, and frequency range are documented.
• The standard method, confidence, source, code/version, and paper references are recorded.
• 2D mesh, port, and frequency convergence studies are separate.
• 2D modes are tracked by physical identity across frequency.
• Fundamental and higher-order cutoffs are reported or marked none.
• 2D candidate and standard results are generated independently.
• 3D mesh, port, domain, runtime, and line-length studies are separate.
• The 3D fixture is uniform and its reference planes are recorded.
• The complete complex S-matrix is preserved.
• Modal/terminal or single-ended/mixed-mode bases are aligned explicitly.
• Below-cutoff and guard-band points are labeled.
• Standard accuracy and numerical convergence are reported separately.
• Raw outputs, compact tables, manifests, and input hashes are preserved.

13. Primary references

Port and result definitions:

• Flex RF wave ports
• Flex RF result processing
• Flex RF meshing

Traceable and high-frequency waveguide references:

• NIST review of IEEE 1785 rectangular-waveguide standards above 110 GHz
• NIST TN 2109: physical models and dimensional traceability of WR15 standards
• NIST guided-wave electromagnetics program
• IET review of substrate-integrated waveguide circuits and antennas

Open-source numerical references:

• openEMS rectangular-waveguide S-parameter tutorial
• MIT Photonic Bands documentation
• Meep mode-decomposition documentation