yonderdrake 0.1.0a1__tar.gz

yonderdrake-0.1.0a1/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Timon S. Gutleb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party components
+
+The Fira Sans and Fira Mono fonts bundled under docs/source/_static/fonts/
+are not covered by the MIT License above. They are licensed under the SIL
+Open Font License 1.1. The full text and copyright notice are in
+docs/source/_static/fonts/LICENSE-Fira.txt.

yonderdrake-0.1.0a1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: yonderdrake
+Version: 0.1.0a1
+Summary: A library for nonlocal time and space operators in Firedrake
+Author: Timon S. Gutleb
+License-Expression: MIT
+Project-URL: Documentation, https://timon.gutleb.com/yonderdrake/
+Project-URL: Homepage, https://github.com/TSGut/yonderdrake
+Project-URL: Issues, https://github.com/TSGut/yonderdrake/issues
+Project-URL: Source, https://github.com/TSGut/yonderdrake
+Keywords: caputo,finite-element-method,firedrake,fractional-calculus,fractional-laplacian
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: test
+Requires-Dist: mpmath>=1.3; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: yonderdrake[test]; extra == "dev"
+Provides-Extra: visual
+Requires-Dist: matplotlib>=3.9; extra == "visual"
+Requires-Dist: pillow>=10; extra == "visual"
+Provides-Extra: docs
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Requires-Dist: myst-parser>=4; extra == "docs"
+Requires-Dist: sphinx<9,>=8; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Dynamic: license-file
+
+<p align="center">
+<img src="https://timon.gutleb.com/yonderdrake/_static/yonderdrake-logo.png"
+     alt="Yonderdrake"
+     width="560">
+</p>
+
+<h1 align="center">Yonderdrake</h1>
+
+<p align="center">
+  Fractional in time, space and other nonlocal operators for
+  <a href="https://www.firedrakeproject.org/">Firedrake</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/TSGut/yonderdrake/actions/workflows/ci.yml"><img src="https://github.com/TSGut/yonderdrake/actions/workflows/ci.yml/badge.svg" alt="Tests"></a>
+  <a href="https://timon.gutleb.com/yonderdrake/"><img src="https://github.com/TSGut/yonderdrake/actions/workflows/docs.yml/badge.svg" alt="Documentation"></a>
+  <a href="https://github.com/TSGut/yonderdrake/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+> **Alpha software:** Yonderdrake has been broadly tested, but bugs and missing
+> features may remain. Please [report them as issues](https://github.com/TSGut/yonderdrake/issues).
+
+Yonderdrake adds various fractional time derivatives, fading-memory operators,
+and spatial fractional Laplacians directly to
+[UFL](https://docs.fenicsproject.org/ufl/main/) forms solved with
+[Firedrake](https://www.firedrakeproject.org/). Time- and space-nonlocal
+operators can also be combined in the same equation.
+
+The eventual goal is to gather all FEM-compatible methods for fractional differential
+equations in one place, so that comparing or switching between them does not
+mean rebuilding the problem each time.
+
+## Features
+
+- Caputo and initialized Riemann-Liouville fractional-in-time derivatives with various methods including static memory diffusive representations, full-history stepping along with additional implementations from the literature for easy comparisons.
+- General single-timescale exponential memory operators, including a convenience wrapper for the Caputo-Fabrizio operator.
+- Homogeneous-Dirichlet spectral, zero-exterior Riesz, and periodic Fourier
+  fractional Laplacians.
+- 2D and 3D Caputo-Wismer waves with heterogeneous density, driven sources,
+  impedance boundaries, PML, configurable sensor arrays, exact adjoints, time
+  reversal, and regularized reconstruction.
+- Variable timesteps, PETSc solver configuration, MPI execution, and checkpoint/restart.
+- Compatibility with [Irksome](https://www.firedrakeproject.org/Irksome/index.html) for classical time stepping alongside Yonderdrake operators.
+
+## Examples
+
+### Fractional time
+
+Three sources in a BrainWeb anatomical head with material-dependent
+Caputo-Wismer damping:
+
+<p align="center">
+  <img src="./demos/demo-output/caputo-wismer-brainweb-sources-readme.gif"
+       alt="Three sources in a BrainWeb anatomical head with fractional damping"
+       width="900">
+</p>
+
+Recovering a vessel-shaped initial pressure from measurements around a
+realistic head. The first two panels compare the true source with its
+reconstruction. The third shows the pressure recorded by the sensor
+array:
+
+<p align="center">
+  <img src="./demos/demo-output/caputo-wismer-brainweb-imaging-readme.png"
+       alt="Vessel-shaped source, reconstructed pressure, and exterior sensor measurements in a BrainWeb head"
+       width="900">
+</p>
+
+### Fractional space
+
+Classical, spectral-fractional, and Riesz heat flow on a Koch snowflake:
+
+<p align="center">
+  <img src="./demos/demo-output/fractional-heat-koch-snowflake.gif"
+       alt="Classical, spectral-fractional, and Riesz heat flow on a Koch snowflake"
+       width="900">
+</p>
+
+See the [guides and examples](https://timon.gutleb.com/yonderdrake/#guides-and-examples)
+for small, reproducible problems and the
+[demo gallery](https://timon.gutleb.com/yonderdrake/gallery/index.html) for the
+full applications.
+
+## Installation
+
+Create a [Firedrake environment](https://www.firedrakeproject.org/install.html):
+
+```console
+git clone https://github.com/TSGut/yonderdrake.git
+cd yonderdrake
+python -m pip install .
+```
+
+Add the plotting dependencies to run the gallery demos or regenerate their
+media:
+
+```console
+python -m pip install '.[visual]'
+```
+
+For development:
+
+```console
+python -m pip install -e '.[dev,docs]'
+```
+
+Firedrake supplies MPI and PETSc. See
+[supported platforms](https://timon.gutleb.com/yonderdrake/support.html).
+
+## Documentation
+
+Start with the [quickstart](https://timon.gutleb.com/yonderdrake/quickstart.html),
+then the [guides and examples](https://timon.gutleb.com/yonderdrake/#guides-and-examples).
+The [mathematics and methods](https://timon.gutleb.com/yonderdrake/#mathematics-and-methods)
+summarize the supported algorithms and the papers behind them. The
+[API reference](https://timon.gutleb.com/yonderdrake/api.html) gives exact
+signatures and restrictions.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for what a numerical change should
+include. LLM-assisted contributions are welcome in principle and are held to
+the same standards as all others. The human author remains responsible for the
+code they submit.
+
+## Logo
+
+The logo nods to the *long memory* of time-fractional operators: a fractional
+derivative still feels the entire history that preceded it. The
+logo dragon is inspired by the
+[Lindwurmbrunnen](https://www.atlasobscura.com/places/lindwurmbrunnen) in Klagenfurt, Austria, drawn in a viridis-like colour scheme.

yonderdrake-0.1.0a1/README.md

@@ -0,0 +1,131 @@
+<p align="center">
+<img src="https://timon.gutleb.com/yonderdrake/_static/yonderdrake-logo.png"
+     alt="Yonderdrake"
+     width="560">
+</p>
+
+<h1 align="center">Yonderdrake</h1>
+
+<p align="center">
+  Fractional in time, space and other nonlocal operators for
+  <a href="https://www.firedrakeproject.org/">Firedrake</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/TSGut/yonderdrake/actions/workflows/ci.yml"><img src="https://github.com/TSGut/yonderdrake/actions/workflows/ci.yml/badge.svg" alt="Tests"></a>
+  <a href="https://timon.gutleb.com/yonderdrake/"><img src="https://github.com/TSGut/yonderdrake/actions/workflows/docs.yml/badge.svg" alt="Documentation"></a>
+  <a href="https://github.com/TSGut/yonderdrake/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+> **Alpha software:** Yonderdrake has been broadly tested, but bugs and missing
+> features may remain. Please [report them as issues](https://github.com/TSGut/yonderdrake/issues).
+
+Yonderdrake adds various fractional time derivatives, fading-memory operators,
+and spatial fractional Laplacians directly to
+[UFL](https://docs.fenicsproject.org/ufl/main/) forms solved with
+[Firedrake](https://www.firedrakeproject.org/). Time- and space-nonlocal
+operators can also be combined in the same equation.
+
+The eventual goal is to gather all FEM-compatible methods for fractional differential
+equations in one place, so that comparing or switching between them does not
+mean rebuilding the problem each time.
+
+## Features
+
+- Caputo and initialized Riemann-Liouville fractional-in-time derivatives with various methods including static memory diffusive representations, full-history stepping along with additional implementations from the literature for easy comparisons.
+- General single-timescale exponential memory operators, including a convenience wrapper for the Caputo-Fabrizio operator.
+- Homogeneous-Dirichlet spectral, zero-exterior Riesz, and periodic Fourier
+  fractional Laplacians.
+- 2D and 3D Caputo-Wismer waves with heterogeneous density, driven sources,
+  impedance boundaries, PML, configurable sensor arrays, exact adjoints, time
+  reversal, and regularized reconstruction.
+- Variable timesteps, PETSc solver configuration, MPI execution, and checkpoint/restart.
+- Compatibility with [Irksome](https://www.firedrakeproject.org/Irksome/index.html) for classical time stepping alongside Yonderdrake operators.
+
+## Examples
+
+### Fractional time
+
+Three sources in a BrainWeb anatomical head with material-dependent
+Caputo-Wismer damping:
+
+<p align="center">
+  <img src="./demos/demo-output/caputo-wismer-brainweb-sources-readme.gif"
+       alt="Three sources in a BrainWeb anatomical head with fractional damping"
+       width="900">
+</p>
+
+Recovering a vessel-shaped initial pressure from measurements around a
+realistic head. The first two panels compare the true source with its
+reconstruction. The third shows the pressure recorded by the sensor
+array:
+
+<p align="center">
+  <img src="./demos/demo-output/caputo-wismer-brainweb-imaging-readme.png"
+       alt="Vessel-shaped source, reconstructed pressure, and exterior sensor measurements in a BrainWeb head"
+       width="900">
+</p>
+
+### Fractional space
+
+Classical, spectral-fractional, and Riesz heat flow on a Koch snowflake:
+
+<p align="center">
+  <img src="./demos/demo-output/fractional-heat-koch-snowflake.gif"
+       alt="Classical, spectral-fractional, and Riesz heat flow on a Koch snowflake"
+       width="900">
+</p>
+
+See the [guides and examples](https://timon.gutleb.com/yonderdrake/#guides-and-examples)
+for small, reproducible problems and the
+[demo gallery](https://timon.gutleb.com/yonderdrake/gallery/index.html) for the
+full applications.
+
+## Installation
+
+Create a [Firedrake environment](https://www.firedrakeproject.org/install.html):
+
+```console
+git clone https://github.com/TSGut/yonderdrake.git
+cd yonderdrake
+python -m pip install .
+```
+
+Add the plotting dependencies to run the gallery demos or regenerate their
+media:
+
+```console
+python -m pip install '.[visual]'
+```
+
+For development:
+
+```console
+python -m pip install -e '.[dev,docs]'
+```
+
+Firedrake supplies MPI and PETSc. See
+[supported platforms](https://timon.gutleb.com/yonderdrake/support.html).
+
+## Documentation
+
+Start with the [quickstart](https://timon.gutleb.com/yonderdrake/quickstart.html),
+then the [guides and examples](https://timon.gutleb.com/yonderdrake/#guides-and-examples).
+The [mathematics and methods](https://timon.gutleb.com/yonderdrake/#mathematics-and-methods)
+summarize the supported algorithms and the papers behind them. The
+[API reference](https://timon.gutleb.com/yonderdrake/api.html) gives exact
+signatures and restrictions.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for what a numerical change should
+include. LLM-assisted contributions are welcome in principle and are held to
+the same standards as all others. The human author remains responsible for the
+code they submit.
+
+## Logo
+
+The logo nods to the *long memory* of time-fractional operators: a fractional
+derivative still feels the entire history that preceded it. The
+logo dragon is inspired by the
+[Lindwurmbrunnen](https://www.atlasobscura.com/places/lindwurmbrunnen) in Klagenfurt, Austria, drawn in a viridis-like colour scheme.

yonderdrake-0.1.0a1/pyproject.toml

@@ -0,0 +1,156 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yonderdrake"
+dynamic = ["version"]
+description = "A library for nonlocal time and space operators in Firedrake"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Timon S. Gutleb" },
+]
+keywords = [
+  "caputo",
+  "finite-element-method",
+  "firedrake",
+  "fractional-calculus",
+  "fractional-laplacian",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+  "numpy>=1.24",
+  "scipy>=1.10",
+]
+
+[project.optional-dependencies]
+test = [
+  "mpmath>=1.3",
+  "pytest>=8",
+  "pytest-cov>=5",
+]
+dev = [
+  "build>=1.2",
+  "mypy>=1.11",
+  "ruff>=0.6",
+  "yonderdrake[test]",
+]
+visual = [
+  "matplotlib>=3.9",
+  "pillow>=10",
+]
+docs = [
+  "furo>=2024.8.6",
+  "myst-parser>=4",
+  "sphinx>=8,<9",
+  "sphinx-copybutton>=0.5",
+]
+
+[project.urls]
+Documentation = "https://timon.gutleb.com/yonderdrake/"
+Homepage = "https://github.com/TSGut/yonderdrake"
+Issues = "https://github.com/TSGut/yonderdrake/issues"
+Source = "https://github.com/TSGut/yonderdrake"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+yonderdrake = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "yonderdrake._version.__version__" }
+
+[tool.pytest.ini_options]
+addopts = "--strict-config --strict-markers -ra"
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = [
+  "ignore:Setting the shape on a NumPy array has been deprecated.*:DeprecationWarning:pyop2.utils",
+]
+markers = [
+  "unit: fast tests of isolated numerical or API components",
+  "verification: numerical verification against an independent reference",
+  "slow: computationally expensive tests",
+  "parallel: tests requiring more than one MPI rank",
+  "performance: non-functional performance measurements",
+]
+
+[tool.coverage.run]
+branch = true
+parallel = true
+relative_files = true
+source = ["yonderdrake"]
+
+[tool.coverage.report]
+fail_under = 97.0
+precision = 1
+show_missing = true
+skip_covered = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src/yonderdrake"]
+strict = true
+no_site_packages = true
+
+[[tool.mypy.overrides]]
+module = ["numpy", "numpy.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+  "firedrake",
+  "firedrake.*",
+  "mpi4py",
+  "mpi4py.*",
+  "petsc4py",
+  "petsc4py.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["ufl", "ufl.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["scipy", "scipy.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "yonderdrake.time._ufl_marker"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = [
+  "yonderdrake._external",
+  "yonderdrake.periodic._external",
+  "yonderdrake.riesz._external",
+  "yonderdrake.spectral._external",
+]
+ignore_errors = true

yonderdrake-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yonderdrake-0.1.0a1/src/yonderdrake/__init__.py

@@ -0,0 +1,61 @@
+"""Yonderdrake public interface."""
+
+from yonderdrake._version import __version__
+from yonderdrake.periodic import PeriodicFractionalLaplacian
+from yonderdrake.riesz import RieszFractionalLaplacian
+from yonderdrake.spectral import SpectralFractionalLaplacian
+from yonderdrake.time import (
+    AlikhanovL21Sigma,
+    AuxiliaryODE,
+    BirkSong,
+    CaputoDerivative,
+    CaputoFabrizioOperator,
+    Cayley,
+    Diethelm2008,
+    Diethelm2022,
+    ExponentialMemory,
+    ExponentialMemoryCompatibilityWarning,
+    FastObliviousCQ,
+    FractionalTimeStepper,
+    FullHistory,
+    LubichCQ,
+    ModeCountAdvisoryWarning,
+    Oscillator,
+    Recurrence,
+    RiemannLiouvilleDerivative,
+    SineDiffusive,
+    StartingCorrectionAdvisoryWarning,
+    SumOfExponentials,
+    TimeMemoryStepper,
+    YuanAgrawal,
+)
+
+__all__ = [
+    "AlikhanovL21Sigma",
+    "AuxiliaryODE",
+    "BirkSong",
+    "CaputoDerivative",
+    "CaputoFabrizioOperator",
+    "Cayley",
+    "Diethelm2008",
+    "Diethelm2022",
+    "FastObliviousCQ",
+    "ExponentialMemory",
+    "ExponentialMemoryCompatibilityWarning",
+    "FractionalTimeStepper",
+    "FullHistory",
+    "LubichCQ",
+    "ModeCountAdvisoryWarning",
+    "Oscillator",
+    "StartingCorrectionAdvisoryWarning",
+    "PeriodicFractionalLaplacian",
+    "Recurrence",
+    "RiemannLiouvilleDerivative",
+    "RieszFractionalLaplacian",
+    "SineDiffusive",
+    "SpectralFractionalLaplacian",
+    "SumOfExponentials",
+    "TimeMemoryStepper",
+    "YuanAgrawal",
+    "__version__",
+]

yonderdrake-0.1.0a1/src/yonderdrake/_external.py

@@ -0,0 +1,80 @@
+"""Common Firedrake registration for linear external operators."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from firedrake import (
+    AbstractExternalOperator,
+    Cofunction,
+    Function,
+    assemble_method,
+)
+
+from yonderdrake._firedrake import (
+    assemble_linear_action_adjoint,
+    assemble_linear_action_matrix,
+)
+
+
+class LinearExternalOperator(AbstractExternalOperator):
+    """Shared registrations for a cached linear primal action."""
+
+    basis_name = "external_operator"
+
+    def _build_manager(self) -> Any:
+        raise NotImplementedError
+
+    def _manager(self) -> Any:
+        current = self.operator_data.get("manager")
+        if current is None:
+            current = self._build_manager()
+            self.operator_data["manager"] = current
+        if float(self.operator_data["order_operand"]) != self.operator_data["order"]:
+            raise RuntimeError(
+                "changing s after construction is unsupported; rebuild the operator"
+            )
+        return current
+
+    def invalidate_cache(self) -> None:
+        self.operator_data["manager"] = None
+
+    @assemble_method(0, (0,))
+    def assemble_forward(self, *, assembly_opts: Any = None) -> Function:
+        del assembly_opts
+        return self._manager().apply(self.ufl_operands[0])
+
+    @assemble_method(1, (0, None))
+    def assemble_jacobian_action(
+        self,
+        *,
+        assembly_opts: Any = None,
+    ) -> Function:
+        del assembly_opts
+        return self._manager().apply(self.argument_slots()[-1])
+
+    @assemble_method(1, (None, 0))
+    def assemble_jacobian_adjoint_action(
+        self,
+        *,
+        assembly_opts: Any = None,
+    ) -> Cofunction:
+        del assembly_opts
+        manager = self._manager()
+        return assemble_linear_action_adjoint(
+            self.function_space(),
+            manager.apply,
+            self.argument_slots()[0],
+            basis_name=f"{self.basis_name}_adjoint_basis",
+        )
+
+    @assemble_method(1, (0, 1))
+    @assemble_method(1, (1, 0))
+    def assemble_jacobian(self, *, assembly_opts: Any = None) -> Any:
+        manager = self._manager()
+        return assemble_linear_action_matrix(
+            self,
+            manager.apply,
+            assembly_opts=assembly_opts,
+            basis_name=f"{self.basis_name}_basis",
+        )