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

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

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.