Metadata-Version: 2.4
Name: dgsolve
Version: 0.1.0a0
Summary: Research-oriented discontinuous Galerkin solvers with first-class discontinuous field support.
Author: DGSolve contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/badulion/discontinuous_systems
Project-URL: Repository, https://github.com/badulion/discontinuous_systems
Project-URL: Issues, https://github.com/badulion/discontinuous_systems/issues
Project-URL: Roadmap, https://github.com/badulion/discontinuous_systems/blob/main/plan.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: numba
Requires-Dist: numba; extra == "numba"
Provides-Extra: viz
Requires-Dist: matplotlib; extra == "viz"
Provides-Extra: io
Requires-Dist: h5py; extra == "io"
Requires-Dist: meshio; extra == "io"
Provides-Extra: jax
Requires-Dist: jax; extra == "jax"
Provides-Extra: cupy
Requires-Dist: cupy; extra == "cupy"
Provides-Extra: petsc
Requires-Dist: petsc4py; extra == "petsc"
Requires-Dist: mpi4py; extra == "petsc"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Dynamic: license-file

# DGSolve

[![CI](https://github.com/badulion/discontinuous_systems/actions/workflows/ci.yml/badge.svg)](https://github.com/badulion/discontinuous_systems/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0a0-orange.svg)](CHANGELOG.md)

**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

```python
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())
```

```bash
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

```python
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

```python
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

```python
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):

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

**Development setup** with [uv](https://docs.astral.sh/uv/):

```bash
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](docs/tutorials/first-solve.md) | 5-minute walkthrough of the Problem API |
| [Discontinuous Fields](docs/tutorials/discontinuous-fields.md) | Raster, piecewise, and region-labeled fields |
| [Meshes](docs/tutorials/meshes.md) | Cartesian, triangular, and AMR meshes |
| [Equations](docs/tutorials/equations.md) | Built-in equations and custom extensions |
| [Fluxes](docs/tutorials/fluxes.md) | Numerical flux selection and custom fluxes |
| [Limiters](docs/tutorials/limiters.md) | TVB, minmod, indicators, custom limiters |
| [AMR](docs/tutorials/amr.md) | Adaptive refinement, indicators, local time stepping |
| [API Reference](docs/api/index.md) | Full public API documentation |
| [Convergence Gallery](docs/gallery/verification/convergence.md) | Smooth advection convergence rates |
| [Limiter Gallery](docs/gallery/limiters/tvb-limiting.md) | TVB limiting on discontinuous data |
| [Blob Advection](docs/gallery/discontinuous-fields/blob-advection.md) | Raster velocity field example |

Build the docs locally:

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

## Testing

```bash
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](plan.md) 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](https://github.com/badulion/discontinuous_systems/issues)
   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](CONTRIBUTING.md) for details.

## License

MIT License. See [LICENSE](LICENSE).

Citation metadata: [CITATION.cff](CITATION.cff).
