[FrederikSchnack]

Summary

Introduce a single, explicit public API for SymPDE and reduce the amount of code and third-party functionality loaded during package imports (fixes #182).

User-facing code should now import supported objects from sympde.api:

from sympde.api import Domain, Square, Mapping
from sympde.api import ScalarFunctionSpace, elements_of
from sympde.api import BilinearForm, LinearForm, integral

Internal SymPDE modules continue to import objects directly from their defining modules.

Public API changes

1. Add an explicit sympde.api namespace

A new sympde.api package provides a documented, flat namespace containing the supported user-facing objects.

The API contains the objects used by the projects that depend on SymPDE (PSYDAC, IGA-Python and GeLaTo) and by the SymPDE documentation, 125 names in total. They were found by collecting all SymPDE imports in these repositories and resolving them to their defining objects. Objects that are only used inside SymPDE or by its unit tests are not part of the API, which keeps sympde/api/__init__.py short and easy to maintain.

The API covers:

• symbolic constants and calculus operators;
• domains, boundaries, interfaces, and mappings;
• scalar and vector function spaces;
• symbolic functions and differential operators;
• variational forms, equations, norms, and integrals, including the 1D forms used by GeLaTo;
• exterior-calculus objects;
• LaTeX printing and domain plotting.

The namespace defines an explicit __all__, making it possible to identify the supported API without relying on implementation details or wildcard imports.

Tests verify that:

• every name in __all__ exists;
• __all__ does not contain duplicates;
• no unintended public names leak into the namespace;
• exported objects are the original objects from their defining modules, rather than wrappers or duplicate definitions.

2. Remove wildcard exports from package initializers (fixes #181)

The previous package initializers recursively imported and re-exported entire subpackages:

from .core import *
from .topology import *
from .exterior import *

Importing a small part of SymPDE could therefore load most of the library, including modules unrelated to the requested functionality.

The initializers for the following packages are now empty:

sympde.calculus
sympde.core
sympde.expr
sympde.exterior
sympde.printing
sympde.topology

The top-level sympde/__init__.py only contains from .version import __version__, so from sympde import __version__ keeps working, as is standard for Python packages. It only loads sympde.version.

This makes imports more predictable and prevents package initialization from eagerly traversing the full dependency graph.

3. Establish separate user-facing and internal import conventions

User code should use the convenient public namespace:

from sympde.api import Domain, Square, grad

Internal library code and the unit tests import directly from the module that defines each object:

from sympde.topology.domain import Domain, Square
from sympde.calculus.core import grad

This separation provides a stable user-facing API while keeping internal dependencies explicit and avoiding circular imports.

Import-performance improvements

4. Avoid loading the complete library for package imports

Previously, imports such as:

import sympde
import sympde.topology.domain

executed wildcard imports from multiple package initializers. This loaded many unrelated symbolic, plotting, mapping, and expression modules.

With empty package initializers, importing a module now loads only its actual dependencies. The complete user-facing namespace is loaded only when explicitly requested through:

import sympde.api

5. Import third-party libraries only where needed (fixes #180)

Some modules imported slow third-party libraries at module level, although only a few of their functions use them:

• sympde.utilities.utils imported matplotlib.pyplot and from mpl_toolkits.mplot3d import *, which are only needed by plot_2d and plot_3d;
• sympde.topology.domain imported h5py, yaml and numpy, which are only needed by Domain.export and Domain.from_file.

These libraries are now imported inside the functions that use them, and the wildcard import is removed. Importing SymPDE, or creating and manipulating symbolic domains, therefore no longer initializes Matplotlib, HDF5 or YAML.

6. Remove unused imports from the library modules

A large number of unused imports were removed from the core, topology, exterior-calculus, expression, and printing modules.

This includes unused:

• NumPy imports;
• SymPy symbols and matrix classes;
• traversal and simplification helpers;
• mapping and topology classes;
• calculus operators;
• legacy compatibility helpers.

Besides reducing import work, this makes each module’s dependency requirements easier to understand.

7. Break circular imports with local imports

The topology derivative module previously imported mapping classes at module scope, while the mapping module also depended on derivative definitions.

Mapping and Jacobian are now imported locally only in the logical-derivative path that needs them.

This removes the module-level cycle without changing the public behavior of differential operators.

Compatibility and cleanup

8. Remove the obsolete SymPy compatibility module

The previous PR replaced usages of the local compatibility helpers with maintained SymPy utilities and native Python metaclass syntax.

Once the package-level wildcard exports are removed, the remaining compatibility module is no longer part of the import surface and can be deleted.

This removes:

sympde/old_sympy_utilities.py

9. Make module-level names used outside their module public

Several module-level names started with an underscore, which marks them as private to their module, although they were used by other SymPDE modules or by PSYDAC. Their underscore is removed:

• _partial_derivatives, _logical_partial_derivatives (sympde.topology.derivatives) and _split_test_function (sympde.expr.evaluation) are used by PSYDAC, and are added to sympde.api;
• _diff_ops, _generic_ops (sympde.calculus.core), _sanitize_arguments (sympde.expr.basic) and _get_domain (sympde.expr.expr) are used by other SymPDE modules only;
• _coeffs_registery (sympde.core.basic) is renamed to coefficient_types, since it is a tuple of types.

The __all__ of every module now lists only public names, and the unused _is_op_test_function is removed from sympde.calculus.core.

10. Import from defining modules in the tests

The unit tests no longer rely on wildcard package exports. Since they are not user-facing, they import every object from the module that defines it, which shows developers exactly which modules a test exercises and keeps sympde.api independent of test coverage.

Dedicated API tests verify:

• package initializers remain empty, except for the version import in the top-level package;
• the API contains only explicitly exported names;
• API exports refer to the canonical definitions;
• no duplicate names are present.

The API checks use direct imports and assertions rather than dynamically executing generated import statements.

11. Fix plotting of unmapped two-dimensional domains

While adding coverage for deferred plotting imports, the unmapped 2D plotting path was found to create a three-dimensional identity mapping.

It now creates the correct two-dimensional identity mapping:

IdentityMapping('Id', dim=2)

A regression test plots an unmapped square with a non-interactive Matplotlib backend and checks that the outline of the unit square is drawn.

Documentation changes

12. Document the supported public API

The README and Sphinx documentation now direct users to sympde.api.

A dedicated API page documents the explicit namespace:

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

The API documentation avoids generating duplicate cross-reference targets for objects that are also documented in their defining modules.

13. Replace obsolete notebooks with executable examples

The old notebooks and their Binder integration had become outdated and were not validated by CI.

They are replaced by focused Python examples covering:

• a quick start;
• analytical mappings;
• differential calculus;
• exterior calculus;
• nonlinear Poisson equations;
• tensorization;
• variational forms and multipatch interfaces.

All examples use the new public API, and so do the docstring examples.

14. Execute documentation examples in CI

The documentation workflow now runs every Python example before building the Sphinx pages:

for example in doc/examples/*.py; do
    python "$example"
done

This ensures that documented imports and examples remain executable as the API evolves.

Obsolete documentation helper scripts, notebooks, notebook styles, and the Binder badge are removed.

15. Draw expression trees in the documentation

The quickstart guide shows the expression trees of two symbolic expressions. A new example script writes them in the DOT language with SymPy's dotprint, and sphinx.ext.graphviz draws them. The graphs are generated from the code at build time, so they always match it. The documentation workflow installs Graphviz for this.

This replaces doc/include/graph.py, which no longer ran, and its pre-rendered images, which are removed.

Breaking changes

Wildcard convenience imports from package namespaces are no longer supported.

For example, user code should migrate from:

from sympde.topology import Domain, Square
from sympde.expr import BilinearForm
from sympde.calculus import grad

to:

from sympde.api import Domain, Square, BilinearForm, grad

Code that intentionally depends on internal implementation details may instead import directly from the defining module:

from sympde.topology.domain import Domain, Square
from sympde.expr.expr import BilinearForm
from sympde.calculus.core import grad

The sympde.api namespace is the recommended interface for downstream users.

The sympde.old_sympy_utilities module is removed. Use sympy.utilities.iterables.is_sequence and Python's metaclass keyword instead of its is_sequence and with_metaclass.

The module-level names _partial_derivatives, _logical_partial_derivatives and _split_test_function lost their leading underscore. Import them as partial_derivatives, logical_partial_derivatives and split_test_function from sympde.api.

Validation

The complete test suite passes:

180 passed, 2 skipped

The documentation validation also passes:

• every documentation example executes successfully;
• Sphinx builds successfully with warnings treated as errors;
• the explicit API namespace is checked for missing, duplicate, or unintended exports;
• public API objects are verified against their canonical definitions;
• deferred plotting imports are covered with a non-interactive regression test.

[yguclu]

Great job!

My single big concern is using the new public interface sympde.api in the unit tests in the tests folders. I have three main reasons to believe we should not do it:

1. The unit tests are not "public-facing", as they only exist to ensure that every library component works as intended.
2. The unit tests should know exactly the SymPDE modules they import from, and show them to the developers.
3. As things progress, we hope that our unit tests will approach 100% coverage of the library. This will make sympde/api/__init__.py a huge file which is not easily maintained.

If we avoid using sympde.api in the unit tests, we could restrict its imports to those needed by the projects that we know for sure to depend on SymPDE. AFAIK those are just PSYDAC, IGA-Python, and GeLaTo. This will make the file much shorter, cleaner, and easier to maintain.

[FrederikSchnack]

Thanks! I agree on all three points.

• In 02e5e21 the unit tests now import every object from its defining module (e.g. from sympde.topology.domain import Square). sympde.api is only used by test_api.py, which tests the namespace itself.
• In 5330690 I restricted sympde.api to the objects that PSYDAC (devel), IGA-Python and GeLaTo import from SymPDE, plus those used by our documentation examples. That brings it from 241 to 122 names. I found these by collecting all SymPDE imports in the three repositories and resolving them to their defining objects. GeLaTo needed the 1D forms (Mass, Stiffness, ...), which were missing before. __version__ is now only in the top-level package.

I also rebased this branch onto the current upgrade_sympy, so it now includes the changes from the review of #193.

[yguclu]

For me this PR is ready to be merged, but I will wait for #193 before approving it

[yguclu]

I have just had another look at the code in this branch. Although not introduced here, there remain several module-level names starting with an underscore, which by Python convention marks them as private to their module, although they are used as public API. Since this PR defines what is public, could you sort them out here?

1. Used by PSYDAC: remove the underscore and add them to sympde.api:

   • _partial_derivatives → partial_derivatives (sympde.topology.derivatives)
   • _logical_partial_derivatives → logical_partial_derivatives (sympde.topology.derivatives)
   • _split_test_function → split_test_function (sympde.expr.evaluation)

2. Used by other SymPDE modules only: remove the underscore, but do not add them to sympde.api:

   • _coeffs_registery → coefficient_types (sympde.core.basic; it is a tuple of types, not a registry)
   • _diff_ops → diff_ops and _generic_ops → generic_ops (sympde.calculus.core)
   • _sanitize_arguments → sanitize_arguments (sympde.expr.basic)
   • _get_domain → get_domain (sympde.expr.expr)

3. Used only inside their module: keep the underscore, but remove them from __all__ in sympde.expr.evaluation, since __all__ lists the public names of a module: _get_trials_tests, _replace_atomic_expr, _split_expr_over_interface, _tensorize_atomic_expr, _to_matrix_form, _unpack_functions.

4. Unused: _is_op_test_function in sympde.calculus.core is never used (sympde/exterior/compiler.py defines its own copy), so it can be deleted together with its __all__ entry.

[FrederikSchnack]

Thanks, done in d2ec86d.

[yguclu]

Thanks @FrederikSchnack, this PR looks excellent now!

A couple of things should probably be changed in the CHANGELOG, though