dgsolve 0.1.0a0

Research-oriented discontinuous Galerkin solvers with first-class discontinuous field support.

DGSolve

Research-oriented discontinuous Galerkin solvers for problems with discontinuous fields and coefficients.

DGSolve is a Python package that treats discontinuous input data as first-class citizens. Where most DG codes bury sharp interfaces, raster-backed velocities, and region labels in one-off scripts, DGSolve keeps them visible in the public API — from field definition through adaptive refinement to VTK export.

---

Quickstart

import numpy as np
import dgsolve as dg
from dgsolve.equations import LinearAdvection
from dgsolve.fields import ConstantVectorField

mesh = dg.CartesianMesh.from_domain(domain=(1.0, 1.0), cells=(16, 16), periodic=True)
velocity = ConstantVectorField((1.0, 0.25))
problem = dg.Problem(
    LinearAdvection(velocity),
    mesh,
    order=1,
    cfl=0.4,
    limiter="tvb",
)

def ic(xy):
    return 1.0 + 0.2 * np.sin(2 * np.pi * xy[..., 0]) * np.cos(2 * np.pi * xy[..., 1])

result = problem.solve(ic, t_final=0.5)
print(result.summary())

pip install .            # install from checkout
uv sync                  # or use uv for development
python first_solve.py    # run it

Features

Solver core

Component	What's included
Equations	LinearAdvection + 14 catalog equations (Euler, shallow water, Burgers, acoustics, diffusion, ...)
Meshes	CartesianMesh (periodic/non-periodic), TriangularMesh, QuadtreeCartesianMesh (AMR)
Bases	Modal Legendre quads, Dubiner triangles, reference interval
Fluxes	Upwind, Lax-Friedrichs (local/global), Rusanov, Central, Godunov
Limiters	TVB, minmod, positivity-preserving, bound-preserving
Time integration	SSPRK2, SSPRK3, RK4, Forward Euler, Low-storage RK, CFL controller
Boundaries	Dirichlet, Neumann, periodic, inflow/outflow, absorbing, reflecting, symmetry
Diagnostics	Mass, L2 norm, min/max tracking, DiagnosticHistory

Discontinuous fields

from dgsolve.fields import RasterVelocityField, PiecewiseConstantVectorField

# Grid-backed velocity from a raster image or array
velocity = RasterVelocityField(vx_grid, vy_grid, origin, spacing)

# Region-labeled piecewise constant velocity
velocity = PiecewiseConstantVectorField(
    regions={"left": (1.0, 0.0), "right": (-0.5, 0.2)},
    default=(0.0, 0.0),
)

Callable, constant, piecewise, raster, and region-labeled fields are all supported. DiscontinuityInterface tracks sharp boundaries explicitly.

Adaptive mesh refinement

from dgsolve.amr import QuadtreeCartesianMesh, AdaptiveDGSolver, JumpAMRIndicator

mesh = QuadtreeCartesianMesh(1.0, 1.0, 8, 8, periodic=True, max_level=4)
indicator = JumpAMRIndicator(refine_threshold=0.05, coarsen_threshold=0.001)
solver = AdaptiveDGSolver(mesh, basis, vel_field, indicator)
U_final, history = solver.solve(U0, T_final=1.0)

• Quadtree h-refinement with 2:1 balance enforcement
• Nonconforming face fluxes (mortar integration at hanging nodes)
• Conservative transfer (L2-projection prolongation/restriction)
• AMR indicators: jump, modal decay, gradient, composite
• Local time stepping via MultirateSolver (level-based subcycling)

IO and visualization

import dgsolve as dg

# Export to ParaView
dg.export_vtk("solution.vtu", U, mesh, basis)
dg.export_xdmf("solution.xdmf", U, mesh, basis)  # requires h5py

# Save/load solver state
dg.save_state("checkpoint.npz", U, t=0.5, step=100)
state = dg.load_state("checkpoint.npz")

# Plot (requires matplotlib)
fig, ax, im = dg.plot_scalar_field(space, U)
fig, ax, lines = dg.plot_diagnostics(history)

Installation

From checkout (recommended during alpha):

git clone https://github.com/badulion/discontinuous_systems.git
cd discontinuous_systems
pip install .

Development setup with uv:

uv sync                  # core + dev tools
uv sync --extra viz      # + matplotlib
uv sync --extra io       # + h5py, meshio
uv sync --extra numba    # + Numba JIT
uv sync --extra docs     # + MkDocs

Documentation

Resource	Description
First Solve	5-minute walkthrough of the Problem API
Discontinuous Fields	Raster, piecewise, and region-labeled fields
Meshes	Cartesian, triangular, and AMR meshes
Equations	Built-in equations and custom extensions
Fluxes	Numerical flux selection and custom fluxes
Limiters	TVB, minmod, indicators, custom limiters
AMR	Adaptive refinement, indicators, local time stepping
API Reference	Full public API documentation
Convergence Gallery	Smooth advection convergence rates
Limiter Gallery	TVB limiting on discontinuous data
Blob Advection	Raster velocity field example

Build the docs locally:

uv sync --extra docs
uv run mkdocs build --strict
uv run mkdocs serve          # live preview at localhost:8000

Testing

python -m unittest discover -s tests -v    # 600+ tests
uv run ruff check src tests                # lint
uv run python -m build && uv run twine check dist/*  # package check

The test suite covers bases, quadrature, meshes, fields, fluxes, limiters, diagnostics, solvers, IO, visualization, AMR (tree, transfer, nonconforming faces, adaptive solver, local time stepping), and backend equivalence.

Repository layout

src/dgsolve/        core package
  amr/              adaptive mesh refinement
  equations/        equation catalog
  fields/           field abstractions
  fluxes/           numerical flux library
  io/               state, config, export (VTK/XDMF)
  limiters/         limiters and indicators
  visualization/    plotting helpers
tests/              600+ unit and integration tests
docs/               MkDocs documentation site
examples/           runnable examples
plan.md             roadmap and milestone plan
CHANGELOG.md        release history

Roadmap

The roadmap is tracked via GitHub milestones. Completed milestones include scalar advection, basis infrastructure, fields, equations, time integration, fluxes, limiters, boundary conditions, diagnostics, AMR, IO, visualization, and documentation.

Future work includes implicit solvers, PETSc/MPI distributed meshes, GPU backends, and broader equation support. These are tracked as explicit milestones so the current release stays honest about its scope.

Contributing

1. Start from a GitHub issue with a clear tag and closing criteria.
2. Create a linked branch: gh issue develop <number> --checkout.
3. Keep changes scoped. Add tests when behavior changes.
4. Open a PR with Fixes #<number> in the body.
5. Wait for CI checks before merging.

See CONTRIBUTING.md for details.

License

MIT License. See LICENSE.

Citation metadata: CITATION.cff.