Improve sympde

[FrederikSchnack]

Modernize SymPDE and clean up its public API

Summary

This PR modernizes SymPDE’s repository setup, documentation, testing workflows, and import interface.

The main objective is to reduce import overhead and provide a clear public API, as requested by issue #182. Additionally, we bump the sympy dependency to its latest version.

It also repairs the documentation infrastructure, migrates documentation publishing to GitHub Pages, and removes obsolete repository content.

Import performance and public API

• 9c336d8 — Defer plotting imports until they are needed.
  Matplotlib and mpl_toolkits were imported whenever sympde.utilities.utils was loaded, even when no plotting was requested. The commit moves Matplotlib imports into the plotting functions and removes the wildcard import. It also fixes the identity-mapping dimension used for unmapped 2D domains. This addresses the expensive and unnecessary imports reported in Avoid useless imports #180.

• 700bf5e — Add an explicit public API.
  Adds sympde.api, whose objects are imported explicitly from their defining modules. It provides one supported convenience namespace without relying on package-level wildcard exports. This implements the first step proposed in Remove unnecessary imports from __init__.py files #181 .

• 1c37b9b — Remove package-level wildcard exports.
  Empties every package initializer except sympde.api, migrates internal imports to defining modules, updates tests and documentation, and removes a hidden import cycle between topology mappings and derivatives. This implements the second step of Remove unnecessary imports from __init__.py files #181.

• fbf29f3 — Avoid dynamic execution in API tests.
  Replaces the exec-based wildcard-import test with direct inspection of sympde.api.all. This preserves API coverage while satisfying static-analysis requirements. It validates the API introduced for Remove unnecessary imports from __init__.py files #181.

• 05b744f — Remove unused production imports.
  Removes 116 unused import bindings from 15 production files, including 84 third-party imports. Imports required by dynamic operator and serialization lookup are retained. This completes the unused-import audit requested by Avoid useless imports #180 .

• 7d5f6ca — Defer domain serialization dependencies.
  Moves NumPy, HDF5, and PyYAML imports into Domain.export() and Domain.from_file(). Ordinary topology imports no longer load these serialization-only dependencies. This resolves another source of unnecessary import cost from Avoid useless imports #180 .

Sympy version

• 457509d — Fix symbolic atom construction for modern SymPy
  ScalarFunction, VectorFunction, and DifferentialForm previously bypassed Symbol.__new__, leaving internal Symbol state such as _assumptions0 uninitialized. Current SymPy accesses that state during normal expression processing and consequently raised errors.
  The classes now use SymPy’s Symbol construction path. Regression tests cover assumptions, commutativity, free symbols, hashing, and differential-form identity.

• 9fcbb54 — Fix integral sum multiplication postprocessing
  mul_add() accidentally wrapped the transformed IntAdd expression in a Python list. Modern SymPy strictly sympifies constructor-postprocessor results and rejected this list while checking form linearity.

  The postprocessor now returns a valid SymPy expression directly.

• bb34a28 — Normalize structural arguments for modern SymPy

  Several custom symbolic objects stored ordinary strings, integers, dictionaries, tuples, or None directly in Basic.args. Modern SymPy expects every element of an expression tree to be a SymPy object, causing failures during traversal and LaTeX printing.

  This commit introduces centralized normalization for structural arguments and applies it to domains, boundaries, interfaces, equations, traces, one-dimensional forms, multipatch mappings, and matrix indices. Public properties still return the established Python-facing values, preserving the existing API.

  It also preserves integer-valued DifferentialForm.dim results and SymPDE’s historical name-based function-symbol identity.

• 2178131 — Support the maintained SymPy release range

  The project dependency was changed from sympy >= 1.5, < 1.10 to sympy >= 1.12, < 1.15.

  The upper bound prevents an untested future SymPy release from being selected automatically. The normal CI matrix tests the newest allowed version, while an additional Python 3.11 job explicitly installs SymPy 1.12 to protect the lower bound.

• 553d8ae — Remove obsolete SymPy compatibility utilities

  Replaced the copied is_sequence implementation with SymPy’s maintained sympy.utilities.iterables.is_sequence and converted singleton classes to native Python metaclass
  syntax.

  The special handling that prevents VectorFunction objects from being interpreted as sequences is now expressed directly at the relevant call sites. Missing is_sequence
  imports were also added to previously untested indexing paths.

  Since SymPDE now requires Python 3.9 and SymPy 1.12, the compatibility helpers are no longer needed and old_sympy_utilities.py was deleted.

Breaking import change

Objects are no longer re-exported from:

• sympde;
• sympde.topology;
• sympde.calculus;
• sympde.expr;
• sympde.exterior;
• sympde.printing; or
• sympde.utilities.

User-facing code should now use:

  from sympde.api import Cube, Mapping, Constant
  from sympde.api import ScalarFunctionSpace, VectorFunctionSpace, elements_of
  from sympde.api import BilinearForm, LinearForm, Norm

Implementation code may instead import objects directly from their defining modules.

sympde.api.__all__ defines the supported wildcard-import surface. Tests verify that it contains no duplicates, exposes no accidental names, and references the objects from their defining modules.

Documentation infrastructure

• 869494a — Repair strict documentation builds.
  Adds reproducible documentation builds, replaces shell-generated API documentation, configures bibliography and MathJax support, and fixes malformed API docstrings. This addresses the broken documentation setup in Failing readthedocs build #166
  and fixes the Domain.join documentation problem from Add docstring to Domain.join() #140 .

• c70890a — Align testing and documentation workflows with Psydac.
  Renames the unit-test workflow to testing.yml, adopts Psydac’s workflow structure, updates the README badge, and formats the documentation workflow consistently. This improves the repository setup associated with Failing readthedocs build #166 .

• 219cbd7 — Migrate documentation to GitHub Pages.
  Publishes strict Sphinx builds from master using GitHub Pages, updates project links, and removes the obsolete Read the Docs configuration. This addresses Failing readthedocs build #166 .

• 3dda950 — Replace obsolete notebooks with tested examples.
  Converts useful notebook content into executable documentation scripts covering variational forms, differential calculus, analytical mappings, exterior calculus, and nonlinear Poisson linearization. The scripts are executed in documentation CI. This
  prevents the examples from becoming stale while updating them to the API introduced for Remove unnecessary imports from __init__.py files #181 .

• a68f1e9— Remove the obsolete TODO file.
  Deletes an unreferenced roadmap from 2019 that describes removed APIs and already-completed work. Current work is tracked through GitHub issues.

Testing and repository maintenance

• 26d16d7— Remove obsolete legacy test artifacts.
  Deletes unmaintained snapshots from old/ and removes bin/run_tests.sh, which references test modules that no longer exist. The maintained pytest suite is now the single documented test entry point.

• 84667d7 — Modernize project metadata and test CI.
  Moves pytest configuration and development dependencies into pyproject.toml, tests the installed package across supported Python versions, and stores coverage as a CI artifact.

Closes #180
Closes #181
Closes #182
Closes #166
Closes #140
Closes #106

[FrederikSchnack]

This PR was split up into #190 #191 #193 #194