Complex Problems Guide

Complex Problems is a plugin subsystem where each problem contributes:

• problem.py descriptor and dialog entry point

• ui.py configuration dialog

• solver.py specialized numerical model

• result_dialog.py custom visualization tabs

• optional model.py helpers

Available modules

ID	Name	Core model	Typical outputs
coupled_oscillators	Coupled Harmonic Oscillators	1D oscillator chain with linear/nonlinear couplings	mode energies, phase-space, recurrence behavior
membrane_2d	2D Nonlinear Membrane	discrete 2D lattice membrane	displacement animation, energy drift, 2D FFT
nonlinear_waves	Nonlinear Waves (NLSE + KdV)	split-step / pseudo-spectral propagation	space-time map, phase/spectrum, invariants
schrodinger_td	Schrodinger TD (1D/2D)	split-operator spectral TDSE	density/phase evolution, expectation values
antenna_radiation	Antenna Radiation	far-field analytical radiation patterns	gain/directivity maps, polar cuts, E/H fields
aerodynamics_2d	Aerodynamics 2D	incompressible flow with projection + obstacle penalization	speed/vorticity maps, Cd/Cl curves
pipe_flow	Pipe Flow	steady Darcy-Weisbach and transient 1D pressure-wave model	pressure/velocity profiles, Reynolds/friction metrics

General usage pattern

1. Open Complex Problems from main menu.

2. Pick a module from the left list.

3. Review the right-side details panel (type, description, configurable options, outputs).

4. Open the selected module.

5. Expand How to configure (collapsed by default) if needed.

6. Configure model-specific parameters.

7. Run solve (background execution + loading dialog).

8. Explore module-specific tabs and diagnostics.

UI notation and text behavior

• Mathematical labels use Unicode notation when possible (xₘᵢₙ, tₘₐₓ, Nₓ, …).

• If a true Unicode subscript is not available, use base_subscript with Unicode symbol, e.g. N_θ, N_φ.

• Static explanatory text is shown as non-editable labels (not copy-oriented text boxes).

• Intentional copy-friendly Unicode helper blocks remain in custom-equation / transform workflows.

Numerical quality checks

Most modules expose magnitude checks in results:

• conservation drift (energy_drift_rel, norm_drift_rel, etc.)

• stability indicators (CFL-like constraints, divergence, max amplitude)

• physical metrics (gain/directivity peaks, drag/lift summaries)

Use these before trusting conclusions from very aggressive settings.

Performance guidelines

• Increase grid resolution only after validating lower-cost runs.

• Keep dt conservative for nonlinear or wave-dominated models.

• Prefer default integrators first; compare alternatives after baseline validation.

• For 2D models, tune both spatial resolution and output sampling cadence.

Extending with new plugins

Follow the package pattern:

src/complex_problems/<plugin_name>/
  __init__.py
  problem.py
  ui.py
  solver.py
  result_dialog.py
  model.py (optional)

Then register the plugin in src/complex_problems/problem_registry.py.

Detailed implementation guidance is in Developer Guide.