psipy — Documentation
\(\psi\pi\) — A Python package for semiclassical analysis, microlocal methods, and geometric PDEs
psipy provides a unified symbolic‑numerical framework for studying linear partial differential equations using techniques from semiclassical analysis, microlocal analysis, and differential geometry. It is designed for both pedagogical exploration and research, with a strong emphasis on asymptotic methods, pseudodifferential operators, and geometric structures.
The package is organised into several modules, each focusing on a specific aspect of the theory. All modules automatically detect the spatial dimension (1D or 2D) from the input data, allowing a consistent interface across problems.
Modules
- asymptotic
Asymptotic evaluation of oscillatory and Laplace‑type integrals I(λ) = ∫ a(x) exp(iλ φ(x)) dx as λ → ∞. Implements stationary phase, Laplace’s method, and saddle‑point (steepest descent) with automatic method selection based on the phase φ.
- caustics
Catastrophe classification (Arnold’s A₂, A₃, A₄, D₄±), detection of ray caustics via the stability matrix, and uniform asymptotic corrections using Airy (fold), Pearcey (cusp), and swallowtail integrals.
- fio_bridge
Fourier Integral Operators: links the pseudodifferential calculus (psiop) with asymptotic evaluation (asymptotic). Builds FIOs for operator actions, propagators, and compositions, delegating all critical‑point work to the asymptotic module.
- geometry
Geometric visualisation and semiclassical analysis of Hamiltonian symbols H(x,ξ). Computes Hamiltonian flows, caustics, periodic orbits, Maslov indices, Gutzwiller trace formula, and produces richly annotated multi‑panel figures.
- microlocal
High‑level microlocal analysis toolkit. Handles characteristic varieties, bicharacteristic flows, wavefront sets, WKB approximations, caustic detection, and Bohr–Sommerfeld quantisation in a dimension‑agnostic way.
- physics
Lagrangian and Hamiltonian mechanics utilities. Performs symbolic and numerical Legendre (and Legendre–Fenchel) transforms, decomposes Hamiltonians into local (polynomial) and non‑local parts, and generates formal PDEs (Schrödinger, wave, stationary).
- propagator
Van Vleck–Pauli–Morette semiclassical propagator. Assembles the full semiclassical wavefunction
ψ(x, t) = Σ_k exp(i S_k/ℏ − i μ_k π/2) / √|det J_k|
from a fan of classical rays traced on any 1D or 2D Riemannian metric defined by a
riemannian.Metricobject (or derived from a Hamiltonian expression H = ½ gⁱʲ pᵢ pⱼ viaMetric.from_hamiltonian).- psiop
Comprehensive symbolic‑numerical environment for pseudodifferential operators. Constructs symbols, computes asymptotic expansions, composes operators (Kohn–Nirenberg / Weyl), builds formal inverses, adjoints, exponentials, and visualises pseudospectra.
- riemannian
Unified Riemannian geometry in 1D and 2D. Defines a metric, computes Christoffel symbols, geodesics, curvature tensors, Laplace–Beltrami operator, and (in 2D) exponential maps, Jacobi fields, and de Rham cohomology quantities.
- solver
Spectral PDE solver for 1D/2D equations with periodic or Dirichlet conditions. Supports linear/nonlinear problems, pseudo‑differential operators, and time‑dependent/stationary equations. Uses Fourier spectral methods and exponential time‑stepping (ETD‑RK4).
- symplectic
Symplectic geometry toolkit for Hamiltonian mechanics with arbitrary degrees of freedom. Provides energy-preserving integrators and symbolic Poisson brackets. Includes fixed-point stability analysis, 1-DOF action-angle/separatrix tools, and 2-DOF Poincaré sections, Lyapunov exponents, and monodromy matrices. Features advanced integrability diagnostics including KAM tori detection, level-spacing statistics (Berry–Tabor and BGS distributions), and rotation numbers.
- wkb
Multidimensional WKB (Wentzel–Kramers–Brillouin) approximation with caustic corrections. Traces rays (bicharacteristics), solves transport equations to arbitrary order, detects caustics via the stability matrix, and applies uniform Airy / Pearcey corrections.
All modules are designed to work together seamlessly while remaining independently usable. The package relies on SymPy for symbolic manipulation, NumPy/SciPy for numerical computation, and Matplotlib for visualisation.
For detailed mathematical background and references, consult the individual module docstrings.
Modules
- asymptotic
- asymptotic.py — Large-parameter asymptotics for oscillatory and Laplace-type integrals
AnalyzerAsymptoticContributionAsymptoticEvaluatorAsymptoticVisualizerCriticalPointIntegralMethodLaplaceEvaluatorSaddlePointEvaluatorSingularityTypeStationaryPhaseEvaluatorStationaryPhaseVisualizerplot_contribution_decomposition()
- caustics
- caustics.py — Catastrophe classification, ray caustic detection, and uniform asymptotic corrections
AdaptiveCriticalPointSolverCausticEventCausticFunctionsRayCausticDetectorclassify_arnold_1d()classify_arnold_2d()detect_catastrophes()find_critical_points_numerical()plot_catastrophe()plot_caustic_events()
- fio_bridge
- geometry
- geometry.py — Geometric visualisation of pseudodifferential symbols in 1D and 2D
CausticStructureGeodesicGeodesic1DGeodesic2DGeodesicBasePeriodicOrbitPeriodicOrbit1DPeriodicOrbit2DPeriodicOrbitBaseSpectralAnalysisSpectrumSymbolGeometrySymbolGeometry2DSymbolGeometryBaseSymbolVisualizerSymbolVisualizer2DSymbolVisualizerBaseUtilities2Dprint_theory()print_theory_summary()visualize_symbol()visualize_symbol_2d()
- hamiltonian_catalog
- hamiltonian_catalog.py — Hamiltonian catalog for analysis, visualization and more…
analyze_hamiltonian()batch_export_hamiltonians()export_latex_table()find_similar_hamiltonians()get_catalog_summary()get_dimensional_analysis()get_hamiltonian()get_hamiltonians_by_keywords()get_operator()get_parameters()get_tree()interactive_hamiltonian()list_categories()list_hamiltonians()print_hamiltonian_info()search_hamiltonians()trace_hamiltonian()validate_hamiltonians()visualize_hamiltonian()
- metric_catalogue
- microlocal
- microlocal.py — Unified microlocal analysis toolkit for 1D and 2D problems
bicharacteristic_flow()bohr_sommerfeld_quantization()characteristic_variety()compute_caustics_2d()compute_maslov_index()find_caustics_1d()plot_bicharacteristics()plot_characteristic_set()plot_wavefront_set()propagate_singularity()
- misc
- physics
- propagator
- psiop
- riemannian
- riemannian.py — Unified 1D/2D Riemannian geometry toolkit
MetricRiemannianGridadd_corrugations()analyze_hodge_decomposition()build_embedding()christoffel()corrugation_step()de_rham_laplacian()distance()exponential_map()geodesic_hamiltonian_flow()geodesic_solver()hodge_decomposition()hodge_decomposition_0form()hodge_decomposition_1form()hodge_decomposition_2form()hodge_star()induced_metric()jacobi_equation_solver()laplace_beltrami()metric_deficit()parallel_transport()plot_corrugation_pipeline()plot_embedding()sturm_liouville_reduce()verify_gauss_bonnet()visualize_curvature()visualize_geodesics()visualize_hodge_decomposition()
- solver
- symplectic
- symplectic.py — Unified symplectic geometry toolkit for Hamiltonian mechanics
IntegrabilityAnalysisSymplecticFormSymplecticForm1D()SymplecticForm2D()action_angle_transform()action_integral()evolve_phase_space_region()find_fixed_points()first_return_map()frequency()hamiltonian_flow()hamiltonian_flow_4d()linearize_at_fixed_point()lyapunov_exponents()monodromy_matrix()phase_portrait()poincare_section()poisson_bracket()project()rectangle_region()separatrix_analysis()symplectic_gradient()visualize_phase_space_structure()visualize_poincare_section()
- wkb
- wkb.py — Multidimensional WKB approximation with caustic corrections
compare_orders()create_initial_data_circle()create_initial_data_line()create_initial_data_point_source()plot_amplitude_decomposition()plot_caustic_analysis()plot_phase_space()plot_with_caustics()visualize_wkb_rays()wkb_approximation()