struphy 3.3.0__tar.gz → 3.4.0__tar.gz

{struphy-3.3.0/src/struphy.egg-info → struphy-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struphy
-Version: 3.3.0
+Version: 3.4.0
 Summary: Multi-model plasma physics package
 Author: Max Planck Institute for Plasma Physics
 Author-email: stefan.possanner@ipp.mpg.de, max.lindqvist@ipp.mpg.de, eric.sonnendruecker@ipp.mpg.de
@@ -31,20 +31,22 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy<=2.5.0
-Requires-Dist: cunumpy<=0.1.5,>=0.1.4
+Requires-Dist: cunumpy<=0.2.0,>=0.2.0
 Requires-Dist: pyccel<=2.2.3,>=2.2.0
-Requires-Dist: feectools<=0.1.10,>=0.1.10
+Requires-Dist: feectools<=0.1.11,>=0.1.11
 Requires-Dist: scipy<=1.18.0
 Requires-Dist: h5py<=3.16.0
+Requires-Dist: h5netcdf<=1.8.1
+Requires-Dist: xarray<=2026.2.0
 Requires-Dist: matplotlib<=3.11.0
 Requires-Dist: pyyaml<=6.0.3
 Requires-Dist: vtk<=9.7.0
 Requires-Dist: tqdm<=4.70.0
 Requires-Dist: argcomplete<=3.7.0
 Requires-Dist: ipywidgets<=8.1.8
-Requires-Dist: plotly<=6.9.0
-Requires-Dist: pyvista<=0.48.0
-Requires-Dist: trame<=3.13.0
+Requires-Dist: plotly<=7.1.0
+Requires-Dist: pyvista<=0.49.0
+Requires-Dist: trame<=4.0.0
 Requires-Dist: trame-vtk<=2.11.8
 Requires-Dist: trame-vuetify<=3.2.2
 Requires-Dist: nest_asyncio2<=1.7.2
@@ -54,14 +56,19 @@ Requires-Dist: pytest-mpi<=0.6
 Requires-Dist: pytest-testmon<=2.2.0
 Requires-Dist: ruff<=0.16.0,==0.15.0
 Requires-Dist: line_profiler<=5.0.2
-Requires-Dist: scope-profiler<=0.5.0,>=0.5.0
+Requires-Dist: scope-profiler<=0.7.2,>=0.5.0
 Provides-Extra: mpi
 Requires-Dist: mpi4py<=4.1.1; extra == "mpi"
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == "gpu"
 Provides-Extra: phys
 Requires-Dist: gvec<=1.5.0,>=1.1.0; extra == "phys"
 Requires-Dist: desc-opt<=0.17.1; extra == "phys"
+Provides-Extra: pproc
+Requires-Dist: plasma-plots>=0.1.0; extra == "pproc"
 Provides-Extra: dev
 Requires-Dist: struphy[mpi]; extra == "dev"
+Requires-Dist: struphy[pproc]; extra == "dev"
 Requires-Dist: notebook; extra == "dev"
 Requires-Dist: autopep8; extra == "dev"
 Requires-Dist: isort; extra == "dev"
@@ -79,6 +86,7 @@ Requires-Dist: scope-profiler[pproc]; extra == "dev"
 Requires-Dist: slurm-script-generator>=0.3.6; extra == "dev"
 Provides-Extra: doc
 Requires-Dist: struphy[phys]; extra == "doc"
+Requires-Dist: struphy[pproc]; extra == "doc"
 Requires-Dist: jupyter; extra == "doc"
 Requires-Dist: nbconvert; extra == "doc"
 Requires-Dist: ipykernel; extra == "doc"
@@ -100,6 +108,7 @@ Requires-Dist: struphy[dev]; extra == "likwid"
 Requires-Dist: pylikwid; extra == "likwid"
 Provides-Extra: all
 Requires-Dist: struphy[phys]; extra == "all"
+Requires-Dist: struphy[pproc]; extra == "all"
 Requires-Dist: struphy[dev]; extra == "all"
 Requires-Dist: struphy[mpi]; extra == "all"
 Requires-Dist: struphy[doc]; extra == "all"
@@ -158,6 +167,8 @@ This will create `params_Maxwell.py` in your current working directory (cwd). Yo
 
 The default output is in `sim_1/` in your cwd. You can change the output path via the class `EnvironmentOptions` in the parameter file.
 
+For plots and diagnostics of the output, install [plasma-plots](https://struphy-hub.github.io/plasma-plots) with `pip install "struphy[pproc]"`; `Output` loads it automatically, adding `out.plot`, `out.analysis` and `.plasma.plot` on every product.
+
 Parallel simulations are run for example with
 
     pip install -U mpi4py

{struphy-3.3.0 → struphy-3.4.0}/README.md

@@ -50,6 +50,8 @@ This will create `params_Maxwell.py` in your current working directory (cwd). Yo
 
 The default output is in `sim_1/` in your cwd. You can change the output path via the class `EnvironmentOptions` in the parameter file.
 
+For plots and diagnostics of the output, install [plasma-plots](https://struphy-hub.github.io/plasma-plots) with `pip install "struphy[pproc]"`; `Output` loads it automatically, adding `out.plot`, `out.analysis` and `.plasma.plot` on every product.
+
 Parallel simulations are run for example with
 
     pip install -U mpi4py

{struphy-3.3.0 → struphy-3.4.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "struphy"
-version = "3.3.0"
+version = "3.4.0"
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [
@@ -24,20 +24,22 @@ classifiers = [
 ]
 dependencies = [
     "numpy<=2.5.0",
-    "cunumpy>=0.1.4, <=0.1.5",
+    "cunumpy>=0.2.0, <=0.2.0",
     "pyccel>=2.2.0, <=2.2.3",
-    "feectools >= 0.1.10, <=0.1.10",
+    "feectools >= 0.1.11, <=0.1.11",
     "scipy<=1.18.0",
     "h5py<=3.16.0",
+    "h5netcdf<=1.8.1",
+    "xarray<=2026.2.0",
     "matplotlib<=3.11.0",
     "pyyaml<=6.0.3",
     "vtk<=9.7.0",
     "tqdm<=4.70.0",
     "argcomplete<=3.7.0",
     "ipywidgets<=8.1.8",
-    "plotly<=6.9.0",
-    "pyvista<=0.48.0",
-    "trame<=3.13.0",
+    "plotly<=7.1.0",
+    "pyvista<=0.49.0",
+    "trame<=4.0.0",
     "trame-vtk<=2.11.8",
     "trame-vuetify<=3.2.2",
     "nest_asyncio2<=1.7.2",
@@ -47,7 +49,7 @@ dependencies = [
     "pytest-testmon<=2.2.0",
     "ruff==0.15.0, <=0.16.0",
     "line_profiler<=5.0.2",
-    "scope-profiler >= 0.5.0, <=0.5.0",
+    "scope-profiler>=0.5.0, <=0.7.2",
 ]
 
 [project.license]
@@ -57,12 +59,19 @@ file = "LICENSE"
 mpi = [
     "mpi4py<=4.1.1",
 ]
+gpu = [
+    "cupy-cuda12x",
+]
 phys = [
     "gvec>=1.1.0, <=1.5.0",
     "desc-opt<=0.17.1",
 ]
+pproc = [
+    "plasma-plots>=0.1.0",
+]
 dev = [
     "struphy[mpi]",
+    "struphy[pproc]",
     "notebook",
     "autopep8",
     "isort",
@@ -81,6 +90,7 @@ dev = [
 ]
 doc = [
     "struphy[phys]",
+    "struphy[pproc]",
     "jupyter",
     "nbconvert",
     "ipykernel",
@@ -104,6 +114,7 @@ likwid = [
 ]
 all = [
     "struphy[phys]",
+    "struphy[pproc]",
     "struphy[dev]",
     "struphy[mpi]",
     "struphy[doc]",
@@ -119,7 +130,6 @@ changelog = "https://github.com/struphy-hub/struphy/blob/devel/CHANGELOG.md"
 
 [project.scripts]
 struphy = "struphy.console.main:struphy"
-kinetic-diagnostics = "struphy.diagnostics.console_diagn:main"
 
 [tool.setuptools.package-data]
 "struphy.fields_background.mhd_equil.eqdsk" = [
@@ -136,6 +146,8 @@ kinetic-diagnostics = "struphy.diagnostics.console_diagn:main"
 ]
 struphy = [
     "compile_struphy.mk",
+    "**/*.cu",
+    "**/*.cuh",
 ]
 
 [tool.autopep8]
@@ -179,6 +191,7 @@ markers = [
     "fluid",
     "kinetic",
     "hybrid",
+    "toy",
     "single",
     "mpi_pic",
 ]

{struphy-3.3.0 → struphy-3.4.0}/src/struphy/__init__.py

@@ -3,10 +3,9 @@ import atexit
 import logging
 import logging.config
 import os
+from typing import TYPE_CHECKING
 
-from feectools.ddm.mpi import mpi as MPI
-
-from struphy.utils.mpi_launch import launched_under_mpi
+from feectools.ddm.mpi import launched_under_mpi
 
 
 class RankZeroFilter(logging.Filter):
@@ -113,7 +112,17 @@ def setup_logging(logging_level: int = logging.WARNING):
     # variables that are typically set by MPI launchers (like mpirun or mpiexec).
     if not launched_under_mpi():
         rank = 0
+        # Serial run: tell feectools not to import mpi4py (which initializes MPI and takes
+        # ~1 s) and use its MockMPI instead. This is an in-process flag, deliberately not an
+        # environment variable, so that it is not inherited by ``mpirun`` subprocesses.
+        # It only has an effect if feectools.ddm.mpi has not been imported yet.
+        import feectools
+
+        feectools.use_mpi = False
     else:
+        # deferred: importing feectools (and thereby mpi4py) is expensive
+        from feectools.ddm.mpi import mpi as MPI
+
         rank = MPI.COMM_WORLD.Get_rank()
     rank_filter = RankZeroFilter(rank)
 
@@ -142,33 +151,65 @@ logger = logging.getLogger("struphy")
 setup_logging(logging_level=logging.WARNING)
 logger.info(f"Logging setup complete, log-file at {config['handlers']['file']['filename']}")
 
-# Import API components
-from struphy.api.compiler import Compiler
-from struphy.api.domains import domains
-from struphy.api.equils import equils
-from struphy.api.grids import grids
-from struphy.api.maxwellians import maxwellians
-from struphy.api.ode import ButcherTableau
-from struphy.api.options import (
-    BaseUnits,
-    DerhamOptions,
-    EnvironmentOptions,
-    FieldsBackground,
-    ProfilingOptions,
-    Time,
-)
-from struphy.api.particles import (
-    BinningPlot,
-    BoundaryParameters,
-    KernelDensityPlot,
-    LoadingParameters,
-    SavingParameters,
-    SortingParameters,
-    WeightsParameters,
-)
-from struphy.api.perturbations import perturbations
-from struphy.api.post_processing import PlottingData, PostProcessor
-from struphy.api.simulation import Simulation
+# Public API components.
+#
+# They are resolved lazily (PEP 562): ``import struphy`` stays cheap, and
+# ``from struphy import X`` only imports the module that actually provides ``X``.
+# Importing everything eagerly pulled in the whole package (geometry, models,
+# post-processing, feectools, ...), costing several seconds.
+_LAZY_API = {
+    "Compiler": "struphy.api.compiler",
+    "domains": "struphy.api.domains",
+    "equils": "struphy.api.equils",
+    "grids": "struphy.api.grids",
+    "maxwellians": "struphy.api.maxwellians",
+    "ButcherTableau": "struphy.api.ode",
+    "BaseUnits": "struphy.api.options",
+    "DerhamOptions": "struphy.api.options",
+    "EnvironmentOptions": "struphy.api.options",
+    "FieldsBackground": "struphy.api.options",
+    "ProfilingOptions": "struphy.api.options",
+    "Time": "struphy.api.options",
+    "BinningPlot": "struphy.api.particles",
+    "BoundaryParameters": "struphy.api.particles",
+    "KernelDensityPlot": "struphy.api.particles",
+    "LoadingParameters": "struphy.api.particles",
+    "SavingParameters": "struphy.api.particles",
+    "SortingParameters": "struphy.api.particles",
+    "WeightsParameters": "struphy.api.particles",
+    "perturbations": "struphy.api.perturbations",
+    "Output": "struphy.api.post_processing",
+    "open_output": "struphy.api.post_processing",
+    "Simulation": "struphy.api.simulation",
+}
+
+if TYPE_CHECKING:  # static analysis and IDEs see the eager imports
+    from struphy.api.compiler import Compiler
+    from struphy.api.domains import domains
+    from struphy.api.equils import equils
+    from struphy.api.grids import grids
+    from struphy.api.maxwellians import maxwellians
+    from struphy.api.ode import ButcherTableau
+    from struphy.api.options import (
+        BaseUnits,
+        DerhamOptions,
+        EnvironmentOptions,
+        FieldsBackground,
+        ProfilingOptions,
+        Time,
+    )
+    from struphy.api.particles import (
+        BinningPlot,
+        BoundaryParameters,
+        KernelDensityPlot,
+        LoadingParameters,
+        SavingParameters,
+        SortingParameters,
+        WeightsParameters,
+    )
+    from struphy.api.perturbations import perturbations
+    from struphy.api.post_processing import Output, open_output
+    from struphy.api.simulation import Simulation
 
 __all__ = [
     "Compiler",
@@ -191,7 +232,22 @@ __all__ = [
     "DerhamOptions",
     "FieldsBackground",
     "ButcherTableau",
-    "PostProcessor",
-    "PlottingData",
+    "Output",
+    "open_output",
     "Simulation",
 ]
+
+
+def __getattr__(name: str):
+    module_name = _LAZY_API.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module_name), name)
+    globals()[name] = value  # cache: later lookups bypass __getattr__
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_API))

struphy-3.4.0/src/struphy/api/post_processing/__init__.py

@@ -0,0 +1,3 @@
+from struphy.post_processing.output import Output, open_output
+
+__all__ = ["Output", "open_output"]

{struphy-3.3.0 → struphy-3.4.0}/src/struphy/compile_struphy.mk

@@ -34,7 +34,7 @@ all: $(OUTPUTS)
 	@for dep in $^ ; do \
 		echo $$dep ; \
     done
-	pyccel compile -v $(FLAGS) $(FLAGS_openmp) $<
+	pyccel compile $(FLAGS) $(FLAGS_openmp) $<
 	@echo ""
 
 #--------------------------------------

{struphy-3.3.0 → struphy-3.4.0}/src/struphy/console/compile.py

@@ -54,6 +54,49 @@ def count_compiled_kernels(state):
     return count_c, count_f90, list_not_compiled
 
 
+def collect_kernel_files(libpath=STRUPHY_LIBPATH):
+    """Return the sorted list of all Struphy kernel source files (absolute paths) below libpath."""
+    tmp = []
+    for subdir, dirs, files in os.walk(libpath):
+        logger.debug(f"\n{subdir = }")
+        if "__pycache__" in subdir or "__pyccel__" in subdir:
+            continue
+        for file in files:
+            logger.debug(f"{file = }")
+            if "kernels" in file and file.endswith(".py") and "_tmp.py" not in file and "test" not in file:
+                tmp += [os.path.join(subdir, file)]
+    return sorted(tmp)
+
+
+def remove_kernel_artifacts(kernel_py):
+    """Remove the compiled extension module, the pyccel lock file and the __pyccel__ sources
+    belonging to a (possibly no longer existing) kernel source file."""
+    import glob
+    import shutil
+
+    dirname, basename = os.path.split(kernel_py)
+    stem = basename[:-3]
+
+    patterns = [
+        os.path.join(dirname, stem + ".*.so"),
+        os.path.join(dirname, stem + ".*.pyd"),
+        os.path.join(dirname, stem + ".lock"),
+        os.path.join(dirname, stem + "_tmp.py"),
+        os.path.join(dirname, "__pycache__", stem + ".*.pyc"),
+        os.path.join(dirname, "__pyccel__", stem + ".*"),
+        os.path.join(dirname, "__pyccel__", stem + "_tmp.*"),
+        os.path.join(dirname, "__pyccel__", "bind_c_" + stem + "*"),
+        os.path.join(dirname, "__pyccel__", stem + "_wrapper.*"),
+    ]
+    for pattern in patterns:
+        for f in glob.glob(pattern):
+            os.remove(f)
+
+    pyccel_dir = os.path.join(dirname, "__pyccel__")
+    if os.path.isdir(pyccel_dir) and not os.listdir(pyccel_dir):
+        shutil.rmtree(pyccel_dir)
+
+
 def struphy_compile(
     language,
     compiler,
@@ -65,6 +108,7 @@ def struphy_compile(
     dependencies,
     time_execution,
     yes,
+    jobs=1,
 ):
     """Compile Struphy kernels. All files that contain "kernels" are detected automatically and saved to state.yml.
 
@@ -100,6 +144,9 @@ def struphy_compile(
 
     yes : bool
         Whether to say yes to prompt when changing the language.
+
+    jobs : int
+        Number of kernels compiled in parallel (default=1). Kernels that depend on each other are still compiled in order.
     """
 
     import importlib.metadata
@@ -124,30 +171,30 @@ def struphy_compile(
     # Read struphy state file
     state = utils.read_state()
 
-    # collect kernels
-    if "kernels" not in state:
-        tmp = []
-        for subdir, dirs, files in os.walk(libpath):
-            logger.debug(f"\n{subdir = }")
-            for file in files:
-                logger.debug(f"{file = }")
-                if (
-                    "kernels" in file
-                    and ".py" in file
-                    and "_tmp.py" not in file
-                    and "test" not in file
-                    and "__pycache__" not in subdir
-                    and "__pyccel__" not in subdir
-                ):
-                    tmp += [os.path.join(subdir, file)]
-
-        state["kernels"] = sorted(tmp)
+    # collect kernels (always re-scan: kernel files may have been added, moved or removed since the last run)
+    kernels_now = collect_kernel_files(libpath)
+    kernels_old = state.get("kernels", None)
 
+    if kernels_old is None:
         # set initial compiler infos to None
         state["last_used_language"] = None
         state["last_used_compiler"] = None
         state["last_used_omp"] = None
-
+    else:
+        removed = sorted(set(kernels_old) - set(kernels_now))
+        added = sorted(set(kernels_now) - set(kernels_old))
+        if removed:
+            print("\nKernel files removed since last compile (deleting stale build artifacts):")
+            for ker in removed:
+                print(f"  {ker}")
+                remove_kernel_artifacts(ker)
+        if added:
+            print("\nNew kernel files detected:")
+            for ker in added:
+                print(f"  {ker}")
+
+    if kernels_old != kernels_now:
+        state["kernels"] = kernels_now
         utils.save_state(state)
     # source files
     sources = " ".join(state["kernels"])
@@ -296,8 +343,11 @@ def struphy_compile(
         #     kernel_file,
         #     "-v",
         # ]
+        # make compiles up to `jobs` kernels at once; the prerequisites computed by
+        # dependencies.py (see compile_struphy.mk) ensure that imported kernels are built first
         cmd = [
             "make",
+            f"-j{jobs}",
             "-f",
             "compile_struphy.mk",
             "sources=" + sources,

{struphy-3.3.0 → struphy-3.4.0}/src/struphy/console/format.py

@@ -105,6 +105,7 @@ PASS_GREEN = f"{GREEN_COLOR}PASS{BLACK_COLOR}"
 
 MODELS_INIT_PATH = os.path.join(LIBPATH, "models/__init__.py")
 PROPAGATORS_INIT_PATH = os.path.join(LIBPATH, "propagators/__init__.py")
+DOMAINS_INIT_PATH = os.path.join(LIBPATH, "geometry/domains/__init__.py")
 
 
 def check_omp_flags(file_path, verbose=False):
@@ -122,14 +123,18 @@ def check_omp_flags(file_path, verbose=False):
     """
     try:
         with open(file_path, "r", encoding="utf-8") as f:
-            if verbose:
-                for iline, line in enumerate(f):
-                    if line.lstrip().startswith("# $"):
-                        print(f"Error on line {iline}: {line}")
-            return all(not line.lstrip().startswith("# $") for line in f)
+            lines = f.readlines()
     except (IOError, FileNotFoundError) as e:
         raise ValueError(f"Error reading file: {e}")
 
+    passes = True
+    for iline, line in enumerate(lines, start=1):
+        if line.lstrip().startswith("# $"):
+            passes = False
+            if verbose:
+                print(f"Error on line {iline}: {line}")
+    return passes
+
 
 def check_ssort(file_path, verbose=False):
     """Check if a file is sorted according to ssort.
@@ -194,15 +199,20 @@ def check_ruff(file_path, verbose=False):
 
         if result.returncode == 0:
             returncodes.append(0)
+        elif command[1] != "format" or result.returncode != 1:
+            # Lint errors (e.g. unsorted imports) or ruff failures
+            returncodes.append(result.returncode)
         else:
             # Default to no error
             returncode = 0
             for line in result.stdout.decode("utf-8").split("\n"):
                 # Skip empty lines and filename headers
-                if not line or line.startswith("+++ "):
+                if not line or line.startswith(("+++ ", "--- ")):
                     continue
-                # Check for lines with actual changes
-                if line.startswith("+ ") and not line[1:].lstrip().startswith("# $"):
+                # Check for lines with actual changes, ignoring the OpenMP flags "#$" -> "# $"
+                if line.startswith("+") and not line[1:].lstrip().startswith("# $"):
+                    returncode = 1
+                if line.startswith("-") and not line[1:].lstrip().startswith("#$"):
                     returncode = 1
             returncodes.append(returncode)
 
@@ -1284,6 +1294,11 @@ def construct_package_init_file(
     per module, by importing each module and collecting the subclasses of `base_class` that
     are defined in it. Preserves the existing module docstring of the `__init__.py`, if any.
 
+    The generated file resolves the classes lazily (PEP 562 module ``__getattr__``), so that
+    ``from package import SomeClass`` only imports the module defining ``SomeClass`` instead of
+    every module in the package. Importing all of them costs a considerable amount of time and
+    is rarely needed. A ``TYPE_CHECKING`` block keeps static analysis and IDEs working.
+
     Parameters
     ----------
     package_dir : str
@@ -1307,22 +1322,61 @@ def construct_package_init_file(
 
     init_content = f'"""{docstring}"""\n\n' if docstring else ""
     class_names = []
+    class_modules = {}
 
     for file_name in sorted(os.listdir(package_dir)):
-        if file_name.endswith(".py") and file_name not in ("__init__.py", *skip):
+        if file_name in ("__init__.py", *skip):
+            continue
+        if file_name.endswith(".py"):
             module_name = file_name[:-3]  # strip .py
-            module = importlib.import_module(f"{package_name}.{module_name}")
-
-            # Loop over all classes in the module
-            for _, cls in inspect.getmembers(module, inspect.isclass):
-                # Only subclasses of base_class defined in this module
-                if issubclass(cls, base_class) and cls.__module__ == module.__name__ and cls != base_class:
-                    class_name = cls.__name__
-                    init_content += f"from {package_name}.{module_name} import {class_name}\n"
-                    class_names.append(class_name)
-
-    init_content += "\n\n"
-    init_content += f"__all__ = {class_names}\n"
+        elif os.path.isfile(os.path.join(package_dir, file_name, "__init__.py")):
+            module_name = file_name  # sub-package laid out as one directory per class
+        else:
+            continue
+        module = importlib.import_module(f"{package_name}.{module_name}")
+
+        # Sub-packages resolve their class lazily via __getattr__; inspect.getmembers would
+        # not see it, so go through __all__ (falling back to what getmembers finds).
+        candidates = [getattr(module, n) for n in getattr(module, "__all__", ())]
+        candidates += [cls for _, cls in inspect.getmembers(module, inspect.isclass)]
+
+        # Loop over all classes in the module
+        for cls in candidates:
+            # Only subclasses of base_class defined in this module (or its sub-modules)
+            if (
+                inspect.isclass(cls)
+                and issubclass(cls, base_class)
+                and cls != base_class
+                and (cls.__module__ == module.__name__ or cls.__module__.startswith(module.__name__ + "."))
+                and cls.__name__ not in class_modules
+            ):
+                class_names.append(cls.__name__)
+                class_modules[cls.__name__] = f"{package_name}.{module_name}"
+
+    init_content += "import importlib\n"
+    init_content += "from typing import TYPE_CHECKING\n\n"
+
+    init_content += "# class name -> module defining it, resolved on first access by __getattr__ below\n"
+    init_content += "_LAZY_IMPORTS = {\n"
+    for class_name in class_names:
+        init_content += f'    "{class_name}": "{class_modules[class_name]}",\n'
+    init_content += "}\n\n"
+
+    init_content += "if TYPE_CHECKING:  # static analysis and IDEs see the eager imports\n"
+    for class_name in class_names:
+        init_content += f"    from {class_modules[class_name]} import {class_name}\n"
+    init_content += "\n"
+
+    init_content += f"__all__ = {class_names}\n\n\n"
+    init_content += "def __getattr__(name: str):\n"
+    init_content += "    module_name = _LAZY_IMPORTS.get(name)\n"
+    init_content += "    if module_name is None:\n"
+    init_content += '        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")\n'
+    init_content += "    value = getattr(importlib.import_module(module_name), name)\n"
+    init_content += "    globals()[name] = value  # cache: later lookups bypass __getattr__\n"
+    init_content += "    return value\n\n\n"
+    init_content += "def __dir__():\n"
+    init_content += "    return sorted(set(globals()) | set(_LAZY_IMPORTS))\n"
     return init_content
 
 
@@ -1344,6 +1398,16 @@ def construct_propagators_init_file(propagators_dir: str = "src/struphy/propagat
     return construct_package_init_file(propagators_dir, "struphy.propagators", Propagator)
 
 
+def construct_domains_init_file(domains_dir: str = "src/struphy/geometry/domains") -> str:
+    """
+    Constructs __init__.py for all domain files by reading actual class names.
+    Skips __init__.py.
+    """
+    from struphy.geometry.base import Domain
+
+    return construct_package_init_file(domains_dir, "struphy.geometry.domains", Domain)
+
+
 def run_formatting_loop(python_files, linters, iterations, verbose):
     """Repeatedly run the given formatters on `python_files` until they are clean.
 
@@ -1481,7 +1545,12 @@ def struphy_build_init_files(config, verbose, yes=False):
     with open(PROPAGATORS_INIT_PATH, "w", encoding="utf-8") as f:
         f.write(propagators_init)
 
-    python_files = [MODELS_INIT_PATH, PROPAGATORS_INIT_PATH]
+    print(f"Rewriting {DOMAINS_INIT_PATH}")
+    domains_init = construct_domains_init_file()
+    with open(DOMAINS_INIT_PATH, "w", encoding="utf-8") as f:
+        f.write(domains_init)
+
+    python_files = [MODELS_INIT_PATH, PROPAGATORS_INIT_PATH, DOMAINS_INIT_PATH]
 
     confirm_formatting(python_files, linters, yes)