[yguclu]

Improve the Geometry class in psydac.cad.geometry, so that all its constructors share the same __init__ method and behave consistently in serial and parallel runs. Fix several bugs in the CAD functions of psydac.cad, and test them extensively.

Geometry class

• All constructors go through __init__(domain, *, ddm, pdim, mappings=None):
  • ddm is a DomainDecomposition (one patch) or a MultiPatchDomainDecomposition (several patches); the number of cells, the periodicity, and the MPI communicator are obtained from it
  • pdim (number of physical dimensions) is mandatory; before, it was always set equal to the number of logical dimensions
  • mappings is optional; if given, each spline mapping must be defined on the domain decomposition of its patch
  • Arguments ncells, periodic, filename, comm, and mpi_dims_mask were removed
  • Direct use of __init__ is discouraged: users should call the factory class methods
• Add factory class method from_file(filename, *, domain=None, comm=None, mpi_dims_mask=None), which replaces Geometry(filename=...) and the method read (removed):
  • If domain is given, it is kept after checking that it matches the topological domain in the file: dimension, patch names, parametric bounds, and interfaces (including their orientation). An error is raised if a patch has no mapping or an analytical mapping
  • Reading multipatch geometries with pdim=1 now works (fixes Geometry cannot read multipatch geometries with pdim=1 #617)
  • The patches of the file are paired with the domain interiors by name; before, they were paired by position, which gave wrong results with 11 patches or more (e.g. patch_10 is sorted before patch_2)
• from_discrete_mapping(mapping, *, name=None) uses the domain decomposition of the mapping's space; arguments comm and mpi_dims_mask were removed
• from_topological_domain requires all the patches of its input domain to be NCubeInterior objects of the same dimension (i.e. all lines, all squares, or all cubes)
• from_topological_domain and from_discrete_mapping use the physical dimension of the mappings (before, it was always equal to the logical dimension)
• Properties mappings, ncells, and periodic are dictionaries keyed by the names of the domain interiors, in the same order; ncells and periodic contain tuples
• Remove property is_parallel
• export raises a ValueError before creating the file if a patch has no spline mapping, instead of an AttributeError with a partially written file (fixes Geometry.export fails with AttributeError for a geometry without spline mappings #631)
• Add docstrings to the class and to all its factory class methods

CAD functions in psydac.cad.cad and psydac.cad.gallery

• elevate and refine use Cartesian control points (as expected by igakit), and the NURBS functions of psydac.cad.gallery return Cartesian (not homogeneous) control points (fixes Inconsistent NURBS control-point conventions distort geometries from cad.gallery, elevate and refine #608)
• translate keeps the weights of NURBS mappings (fixes cad.translate drops the weights of NURBS mappings #609)
• elevate and refine accept spline mappings (fixes cad.elevate and cad.refine reject spline mappings #610)
• elevate and refine work for distributed mappings (fixes cad.elevate and cad.refine are wrong for distributed mappings #611)
• elevate and refine work for mappings with pdim=1 (fixes psydac.cad.elevate and refine fail for mappings with pdim=1 #618)
• refine works when inserting a value which is already a knot (fixes psydac.cad.refine fails when inserting a value which is already a knot #619)
• Reduce code duplication between elevate and refine, add docstring to translate, and remove the obsolete __main__ demo from psydac.cad.cad
• The obsolete __main__ demo in psydac/cad/gallery.py is left for a separate PR (see Add exact NURBS geometries from psydac.cad.gallery to psydac mesh, with an option to plot #620)

Other library changes

• discretize(domain, filename=...) creates the geometry with Geometry.from_file(filename, domain=domain, ...), hence it keeps the given domain after checking that it matches the file
• discretize_space and PostProcessManager look up the spline mappings by interior name only
• NurbsMapping.__init__ checks that the weights field belongs to the mapping's space (fixes NurbsMapping.__init__ does not check the weights field #616)
• DomainDecomposition stores mpi_dims_mask (new property), which is kept by TensorFemSpace.add_refined_space and psydac.cad.cad.refine (fixes DomainDecomposition does not store mpi_dims_mask, which breaks refined spaces #622). Fix the number of local cells in DomainDecomposition.refine (fixes DomainDecomposition.refine returns a decomposition with wrong local_ncells #623)
• psydac.fem.partitioning.partition_coefficients raises a ValueError with an explanation, instead of an AssertionError, when an MPI process owns too few coefficients
• In psydac.mapping.discrete_gallery, add function get_available_mappings, add option mpi_dims_mask to discrete_mapping, give it explicit keyword-only arguments and a docstring
• Support NumPy 2.5: avoid setting the shape of NumPy arrays (deprecated since NumPy 2.5) in KroneckerLinearSolver, and use the latest version of Igakit (commit dalcinl/igakit@2a0c9ee), which includes the same fix
• Fix error message (a NameError was raised instead) in get_max_degree_of_one_space
• Use SymPDE version 0.20.0, always provide the interface orientation to Domain.join, and add the interface orientation to the multipatch geometry files in psydac/cad/mesh/multipatch
• Update the polar examples to the new Geometry API: factory methods and local imports in poisson_2d.py, and from_discrete_mapping without comm in polar_model_2d.py
• psydac/cad/__init__.py no longer imports the submodules of psydac.cad
• Remove unused imports in all the Python files changed by this PR

Unit tests

• New module psydac.cad.tests.test_cad: check that translate, elevate, and refine preserve the geometry, for spline and NURBS mappings, for curves in 1D/2D/3D, surfaces in 2D/3D, and volumes in 3D, both in serial and in parallel
• New module psydac.cad.tests.test_gallery: check the circular edges of the NURBS gallery mappings
• psydac.cad.tests.test_geometry:
  • Check round trips through file export/import and from_discrete_mapping, in 1D and 2D, and for NURBS curves in 1D/2D/3D and surfaces in 3D
  • Test from_file with correct and wrong domains, with one and two patches, in 1D and 2D
  • Test from_file with 11 patches, to check that the patches are paired with the domain interiors by name
  • Test that export raises a ValueError, without creating a file, for a geometry without spline mappings
  • Test __init__ without mappings, and reading a multipatch geometry file
  • Remove obsolete tests, and write all HDF5 files to temporary directories (fixtures tmp_path from Pytest and mpi_tmp_path from pytest-mpi), so that the tests can run in parallel with pytest-xdist
• New module psydac.api.tests.test_discretization, testing get_max_degree_of_one_space and get_max_degree
• Test the check of the weights field in NurbsMapping.__init__
• Write the plot of the multipatch Poisson test to a temporary directory
• New module psydac.ddm.tests.test_cart: test the property mpi_dims_mask of DomainDecomposition, and check that DomainDecomposition.refine keeps the process grid (DomainDecomposition does not store mpi_dims_mask, which breaks refined spaces #622) and the number of local cells (DomainDecomposition.refine returns a decomposition with wrong local_ncells #623), in parallel
• New module psydac.fem.tests.test_partitioning: check that partition_coefficients raises a ValueError when an MPI process owns too few coefficients, for periodic and non-periodic spaces (at least 2 processes)

Continuous integration and developer tools

• Use ubuntu_installations action in documentation workflow, and name the checkout step in testing workflow
• Add Pylint configuration to pyproject.toml, and configure isort with the profile of black, so that the two tools agree
• Add AGENTS.md with developer rules: project overview, tech stack, code standards, testing conventions (including MPI tests), file structure, workflow (squash merge, CHANGELOG format, issues), and lint checks to run on the changed files

[yguclu]

@campospinto I have tried to address all of your comments

[campospinto]

Thanks ! I see one possible issue, described in a comment, then I would approve the PR

[campospinto]

thanks! I think the PR is now good to go

[yguclu]

@campospinto Thanks for the review!

I am doing some final cleanup and running the CI workflows once again. I am going to merge this PR shortly afterwards