Broken-FEEC conforming projections in polar domains

[alisa-kirkinskaia]

Provide broken-FEEC conforming projection operators (as matrix-free LinearOperator subclasses) for the $C^0$ and $C^1$ sequences in 2D disk-like domains with a polar singularity (conga_projections.py). Implement explicit formulas of the matrix entries from Sections 3.4-3.5 (pages 19-24) of the arXiv preprint. Provide 2D examples (Poisson and Maxwell). Make everything work in parallel with MPI.

Main additions

Broken-FEEC conforming projection operators

Create new module psydac.feec.polar.conga_projections with the LinearOperator subclasses:

• C0PolarProjection_V0/1/2 acting on the coefficients of scalar- or vector-valued tensor-product splines defined on the logical domain. The tensor-product splines are projected onto the subspaces $\{V_h^0, V_h^1, V_h^2\}$ of 0/1/2-form splines with $C^0$ smoothness after the push-forward.
• C1PolarProjection_U0/1/2 acting on the coefficients of scalar- or vector-valued tensor-product splines defined on the logical domain. The tensor-product splines are projected onto the subspaces $\{U_h^0, U_h^1, U_h^2\}$ of 0/1/2-form splines with $C^1$ smoothness after the push-forward.

The dot methods of the new projection operators correctly execute in parallel for arbitrary domain decompositions in both the angular and radial dimensions.

Tests

Create new test module psydac.feec.polar.tests.test_conga_projections with MPI-parallel unit tests which check:

• The projection property P(P(x)) = P(x)
• tosparse methods against reference matrix operators
• Consistency between dot and tosparse methods

Poisson and Maxwell examples

Provide MPI-parallel 2D examples of broken-FEEC discretizations in mapped polar domains:

• Script psydac/feec/polar/examples/poisson_2d.py solves manufactured Poisson problems in polar mapped domains. The script supports disk, target, and Czarny domains, analytical or spline mappings, and different treatments of the polar singularity (polar-spec, polar-std, C0conga, and C1conga).
• Script psydac/feec/polar/examples/maxwell_2d.py solves time-dependent TE (transverse electric) electromagnetic wave propagation in circular domains. The parametrization allows for a "Shafranov shift" of the polar singularity, which is treated with the broken-FEEC approach, imposing either $C^0$ or $C^1$ continuity. Two different solutions are available, both defined in psydac/feec/polar/examples/analytical_solutions.py:
  • CircularCavitySolution: manufactured time-harmonic solution of Maxwell's equations in a disk with perfectly conducting walls
  • GaussianInitialCondition: localized rotational Gaussian initial condition for the electric field, with the magnetic field initialized from $B_z = \mathrm{curl} E$

Both examples use two new modules in the same directory:

• psydac.feec.polar.examples.polar_model_2d provides the base class PolarModel2D for analytical models on mapped 2D polar domains.
• psydac.feec.polar.examples.utils_congapol provides various utility functions.

Further changes

• Add module psydac.utilities.parallel_utils for parallel execution and gathering variable-length arrays
• Add module psydac.utilities.operators with class Laplacian used in some old examples
• Use latest version of Igakit (commit dalcinl/igakit@92ee097 of 2026/07/24) which supports NumPy >= 2.4
• Use SymPDE version 0.19.3 which fixes a bug in the linearity checks
• Fix a bug in eval_field and eval_field_gradient of TensorFemSpace related to floating point round-off at MPI subdomain boundaries. Add a unit test in psydac/fem/tests/test_eval_fields_parallel.py
• Update GitHub Actions versions to avoid deprecation warning of Node.js 20

Additional info

• Poisson example
  Example of run: mpirun -n 2 python poisson_2d.py -S -n 16 24 -d 2 2 -t disk -D 0.2 -m 'C0conga'
  Exact solution, approximate solution and error plot:

• TE Maxwell example
  Example of run: mpirun -n 2 python maxwell_2d.py -S -n 16 20 -d 2 2 -T 1 -D 0.2 -s 1
  Plot of exact solution and approximate solution at final time T = 1:

TODO

• Add missing class C1PolarProjection_V2 and test it
• Rename C1PolarProjection_V0/1/2 to C1PolarProjection_U0/1/2 (i.e. replace V with U)
• Put analytical solutions in a single module (instead of two) given the amount of duplicated code
• Mention analytical solutions in PR description
• Speed up help messages in example scripts
• Reduce size of output figures so that they fit on a laptop screen
• Provide utility function(s) to handle parallel scripts
• Collect MPI utilities in a single module
• Address TODOs in Maxwell script
• Replace sympy.lambdify with pyccel.lambdify
• Add license header to all new files
• Investigate crash when running maxwell_2d.py in parallel for a certain combination of degree and ncells
• Savage main function in waveTE.py
• Update PR description
• Update CHANGELOG.md
• Make new modules and examples show up in the documentation

[yguclu]

@alisa-kirkinskaia I have made some small additional changes to the docstrings in order to have the Sphinx documentation in full order.

At this point I think there is only one thing missing for this PR to be merged, which is a slight change in notation in the docstrings of module feec.polar.conga_projections:

1. The docstrings reference "pre-polar" spaces which are not mentioned in the final version of the manuscript, so the language should be updated.
2. The LinearOperator objects in that module correspond to the matrices $\mathbb{P}^{\ell}_V$ and $\mathbb{P}^{\ell}_U$ (for $\ell \in \{0, 1, 2\}$) acting on the coefficient vectors, rather then the projection operators acting on the spline functions; this should also be changed/clarified in the docstrings.

[alisa-kirkinskaia]

@alisa-kirkinskaia I have made some small additional changes to the docstrings in order to have the Sphinx documentation in full order.

At this point I think there is only one thing missing for this PR to be merged, which is a slight change in notation in the docstrings of module feec.polar.conga_projections:

Thanks! I updated the docstrings in 315eb7e

[yguclu]

I am suggesting small changes in order to fix a couple of mismatches between the docstring of class C0PolarProjection_V0 and the reference manuscript. If the Sphinx documentation is built correctly, I would like you to make similar changes to the other classes

[yguclu]

Good job!

We are almost finished with the review process