Skip to main content

pydgq

top language supported Python versions supported implementations CI status

version on PyPI PyPI package format dependency status

license open issues PRs welcome

Solve ordinary differential equation (ODE) systems using the time-discontinuous Galerkin method, with Cython acceleration.

We use semantic versioning.

For my stance on AI contributions, see the collaboration guidelines.

Lorenz attractor, dG(2)

Introduction

This is a Cython-accelerated library that integrates initial value problems (IVPs) of first-order ordinary differential equation (ODE) systems of the form u'(t) = f(u, t).

The main feature of the library is dG(q), i.e. the time-discontinuous Galerkin method using a Lobatto basis (a.k.a. hierarchical polynomial basis). Some classical explicit and implicit integrators (RK4, RK3, RK2, FE, SE, IMR, BE) are also provided, mainly for convenience.

Time-discontinuous Galerkin is a very accurate implicit method that often allows using a rather large timestep. Due to its Galerkin nature, it also models the behavior of the solution inside the timestep (although best accuracy is obtained at the endpoint of the timestep).

Arbitrary polynomial degrees q are supported, but often best results are obtained for q = 1 (dG(1)) or q = 2 (dG(2)). (The example image above has been computed using dG(2). Note the discontinuities at timestep boundaries.)

The focus of this library is on arbitrary nonlinear problems. All implicit methods are implemented using fixed-point (Banach/Picard) iteration, relying on the Picard-Lindelöf theorem (which itself relies on the Banach fixed point theorem).

For supplying the user code implementing the right-hand side (RHS) f(u, t) for a given problem, both Python and Cython interfaces are provided.

For material on the algorithms used, see the user manual.

Installation

From PyPI

pip install pydgq

From source

git clone https://github.com/Technologicat/pydgq.git
cd pydgq
pip install .

Performance builds

The default build uses meson's release optimization (-O2). For numerically intensive workloads, you can enable architecture-specific optimizations:

CFLAGS="-march=native -O2 -msse -msse2 -mfma -mfpmath=sse" pip install --no-build-isolation .

Note: wheels on PyPI are built without -march=native for portability. Build from source if you want maximum performance on your specific hardware.

Development

pdm install                              # creates venv, installs dev deps
pip install --no-build-isolation -e .    # editable install (needs venv activated)
pdm run pytest tests/ -v                 # run tests

The --no-build-isolation flag is required for editable installs with meson-python — the on-import rebuild mechanism needs build dependencies to remain available in the environment.

PATH note: The meson-python editable loader needs meson and ninja on PATH. If you get rebuild errors, ensure the venv's bin/ is on the path:

export PATH="$(pwd)/.venv/bin:$PATH"

Usage summary

The user is expected to provide a custom kernel, which computes the RHS f(u, t) for the specific problem to be solved.

The problem is solved by instantiating this custom kernel, and passing the instance to the ivp() function of the pydgq.solver.odesolve module (along with solver options).

A Cython example kernel is provided in pydgq.examples.example_kernel. A standalone visualization script (Lorenz attractor) is in examples/.

Software architecture

The design of pydgq is based on two main class hierarchies, consisting of Cython extension types (cdef classes):

  • IntegratorBase: interface class for integrator algorithms
    • ExplicitIntegrator: base class for explicit methods, which are implemented in pydgq.solver.explicit:
      • RK4: fourth-order Runge-Kutta
      • RK3: Kutta's third-order method
      • RK2: parametric second-order Runge-Kutta
      • FE: forward Euler (explicit Euler)
      • SE: symplectic Euler, for 2nd-order systems reduced to a twice larger 1st-order system
    • ImplicitIntegrator: base class for implicit methods, which are implemented in pydgq.solver.implicit:
      • IMR: implicit midpoint rule
      • BE: backward Euler (implicit Euler)
      • GalerkinIntegrator: base class for Galerkin methods using a Lobatto basis, which are implemented in pydgq.solver.galerkin:
        • DG: discontinuous Galerkin
        • CG: continuous Galerkin
  • KernelBase: interface class for RHS kernels
    • CythonKernel: base class for kernels implemented in Cython, see pydgq.solver.builtin_kernels for examples:
      • Linear1stOrderKernel: w' = M w
      • Linear1stOrderKernelWithMassMatrix: A w' = M w
      • Linear2ndOrderKernel: u'' = M0 u + M1 u'
        • solved as a twice larger 1st-order system, by defining v := u', thus obtaining u' = v and v' = M0 u + M1 v
        • the DOF vector is defined as w := (u1, v1, u2, v2, ..., um, vm), where m is the number of DOFs of the original 2nd-order system.
      • Linear2ndOrderKernelWithMassMatrix: M2 u'' = M0 u + M1 u'
        • solved as u' = v and M2 v' = M0 u + M1 v similarly as above
      • CythonKernel acts as a base class for your own Cython-based kernels
    • PythonKernel: base class for kernels implemented in Python
      • PythonKernel acts as a base class for your own Python-based kernels

The ivp() function of pydgq.solver.odesolve understands the IntegratorBase and KernelBase interfaces, and acts as the driver routine.

Aliases to primitive data types (to allow precision switching at compile time) are defined in pydgq.solver.types: Python (import), Cython (cimport). The Python-accessible names point to the appropriate NumPy symbols. RTYPE is real, ZTYPE is complex, and DTYPE is an alias representing the problem data type. The corresponding Cython-accessible datatypes have the _t suffix (RTYPE_t, ZTYPE_t, DTYPE_t).

Currently, DTYPE is real, but it is kept conceptually separate from RTYPE so that complex-valued problems can be later supported, if necessary (this requires some changes in the code, especially any calls to dgesv).

Linear and nonlinear problems

The built-in kernels concentrate on linear problems, because for this specific class of problems, it is possible to provide generic pre-built kernels. The provided set of four kernels attempts to cover the most common use cases, especially the case of small-amplitude vibration problems in mechanics, which are of the second order in time, and typically have all three matrices M0, M1 and M2.

The main focus of the library, however, is on solving arbitrary nonlinear problems, and thus no algorithms specific to linear problems have been used. This makes the solver severely suboptimal for linear problems, but significantly increases flexibility.

Be aware that due to this choice of approach, the usual stability results for integrators for linear problems do not apply. For example, BE is no longer stable at any timestep size, because for large enough dt, contractivity in the Banach/Picard iteration is lost. (The standard results are based on classical von Neumann stability analysis; without modifications, these arguments are not applicable to the algorithm based on Banach/Picard iteration.)

Lobatto basis functions / precalculation

The numerical evaluation of the Lobatto basis functions is numerically highly sensitive to catastrophic cancellation (see the user manual); IEEE-754 double precision is insufficient to compute the intermediate results. To work around this issue, the basis functions are pre-evaluated once, by the module pydgq.utils.precalc, using higher precision in software (via mpmath).

The precalculation can be run again by running the module as the main program, e.g. python -m pydgq.utils.precalc. The module has some command-line options; use the standard --help option to see them.

The precalc module stores the values of the basis functions (at quadrature points and at visualization points, both on the reference element [-1,1]) into pydgq_data.npz, a compressed NumPy archive.

A data file with default precalc settings (q = 10, nx = 101) is included in the package. It is architecture-independent.

When running the solver, to use Galerkin methods, pydgq.solver.galerkin.init() must be called before calling pydgq.solver.odesolve.ivp().

Data file location

During pydgq.solver.galerkin.init(), the solver attempts to load pydgq_data.npz from these locations, in this order:

  1. ./pydgq_data.npz (local override),
  2. ~/.config/pydgq/pydgq_data.npz (user override),
  3. Installed package data, via importlib.resources.

If all three steps fail, an error is raised.

Dependencies

Runtime: NumPy, PyLU

Build: Cython (≥ 3.0), meson-python

Precalculation only: mpmath (extended-precision arithmetic for Lobatto basis evaluation)

Examples: Matplotlib (for the Lorenz visualization script in examples/)

License

BSD. Copyright 2016-2026 Juha Jeronen and University of Jyväskylä / JAMK University of Applied Sciences.

Acknowledgement

This work was financially supported by the Jenny and Antti Wihuri Foundation.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydgq-1.0.1.tar.gz (849.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pydgq-1.0.1-cp314-cp314-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.14Windows x86-64

pydgq-1.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pydgq-1.0.1-cp314-cp314-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

pydgq-1.0.1-cp313-cp313-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.13Windows x86-64

pydgq-1.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pydgq-1.0.1-cp313-cp313-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

pydgq-1.0.1-cp312-cp312-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.12Windows x86-64

pydgq-1.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pydgq-1.0.1-cp312-cp312-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

pydgq-1.0.1-cp311-cp311-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.11Windows x86-64

pydgq-1.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pydgq-1.0.1-cp311-cp311-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

File details

Details for the file pydgq-1.0.1.tar.gz.

File metadata

  • Download URL: pydgq-1.0.1.tar.gz
  • Upload date:
  • Size: 849.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydgq-1.0.1.tar.gz
Algorithm Hash digest
SHA256 b2fc2325f7ca9627d5a0097b34be31a39fa5bd440f23e3a7436c7ebe5386095e
MD5 d7e92664b75850b412a003f31f4466e5
BLAKE2b-256 d954535ba76e700248e17d0ad6a0c961c567698343841a1d2d6006dce1d6ef55

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1.tar.gz:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: pydgq-1.0.1-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydgq-1.0.1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 170ebb494869d5784dc1a605b0cfcff221ca4dc97d34706634dd94ed08afef5b
MD5 940671cc45a888e68e0e771eccf179b0
BLAKE2b-256 cfa5bb573dbcdf21f6fe9d11cd63ace29581ea1da343ce38751ac2bfc67bbe7d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp314-cp314-win_amd64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 4290a32caf1ad5d6a6f30699a643e357c9a0b77a8c062ded5ef713d653cd1674
MD5 65da78f71bc466f7b9c09ff410adf3ea
BLAKE2b-256 95d2da1795d0233638ab2c947163b978ac52d6bd990f70e37ac05d02ad45f193

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c528d746040aeaa8b370bdce8e196443c37a90a60deac09b458c05099a23598e
MD5 101c8cca6906bb2e12c3596d76de21b0
BLAKE2b-256 2dad58968e1511969c23734df1949ec2a6926cb483a848ee23d1a469887082bd

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: pydgq-1.0.1-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydgq-1.0.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 cc7b1dc914dad7804882eae8d5079382c467e7c66f2777d72911c9a788d0dfb0
MD5 6084d58409e7ce1435cb0e2b96c4ca68
BLAKE2b-256 5100d699c3cf34c57488128c1bae3b44922f7f48ab82ae16854797ac9160e1ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp313-cp313-win_amd64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 02060bb72aea60060601abf3572a6d497508edc7ac98590d4a520d17b6c9ba3c
MD5 723978ad1db4d4d2589c21c3571108af
BLAKE2b-256 81e3e04780a02dc333ff1c3ce50e475f4f448214f205878eb0cafc5c82644095

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8c50e604b1152670ad9b6ec800ac67bed0a1282c9afcb4d432c2279f63d50da2
MD5 9de85c35e462599b083e9b9ae54569c5
BLAKE2b-256 553ed5ea54638888690a44ea7b5391d0acb0c7c2bafaa6157a85852878d79087

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: pydgq-1.0.1-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydgq-1.0.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 e05b6b47133e4c4569c1c078fea85e469eb60954fe78ec7dbb99a5955b26414a
MD5 e3f5badc752679bfd7f8b5c94e2c23ca
BLAKE2b-256 545de952eab2fab8249c08687e40c93fdd056110d5677694aaec00e21392e25b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp312-cp312-win_amd64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 725e5eac4bc698456530687be23050195c29fdb96d40bf5d26f40af6045bf93f
MD5 c947fe595c49b928382e92a3313dc4ab
BLAKE2b-256 f48a91a9395e69ea82184e1a3e690ad33ca726ebd7652f111a75fd58a92ba56c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dcff0ac14a46608c963b83426d9e0ac2fc9b4de01d61a0e2ddcbce07831649cd
MD5 08beefd7d6cc5770f93e5f737d59f07a
BLAKE2b-256 73c77b8b87c9b64d0464abea83ce49b792048aa3d0447eced5073d9ae30d6ffd

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: pydgq-1.0.1-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydgq-1.0.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 078718fe1a42fe6575ce1f630a1c7d8265fb6b63c7790f25467f238a9dd18fb5
MD5 04cafe4eb153ba872e6e4f81a0f04660
BLAKE2b-256 1ad47f51a4f8bcedcc7285eb89fceece1e5d9792233b31117d94add078a27f48

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp311-cp311-win_amd64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2d9a3fc2c0737c7303e3850a11502a6b365bb68c12e4f6555f1a842055d8bdec
MD5 a4ce54e9707f6edef4b052cdf9737303
BLAKE2b-256 0f61d78e9a66d55ad58bf00013e7188e6fc9c0f1e0d16954c9451690f3c7074c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydgq-1.0.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pydgq-1.0.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 175071b88ad09593eda1a20396f358d1a84bcfc40db8cf16a8e9461573255252
MD5 a3534a28dbadbdd5598d4c853fe989ad
BLAKE2b-256 fe096363c5e8ea901b553e6c3e7328b0c7bb5212a9c3c3de45bf645c82b2e00b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydgq-1.0.1-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: ci.yml on Technologicat/pydgq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.1.0

16 files

This release

1.0.1 This release

13 files

1.0.0

13 files

0.1.2

1 file

0.1.1

1 file

0.1.0

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page