alexfikl / pyshocks

Automatic Differentiation + Adjoint + Shocks Experiments

About

This repository contains some preliminary experiments on performing adjoint-based optimization of systems with shocks by using automatic differentiation. The main goal is to get it working for the one-dimensional unsteady Euler equations with common WENO schemes.

It is currently quite far from that goal, so this is very experimental.

Requirements

The project currently supports Python 3.8 and later. The (full) requirements are listed in pyproject.toml.

• jax and jaxlib: base numeric and automatic differentiation package used throughout. See JAX support policy for details on supported versions.
• rich: recommended for nicer logging.
• matplotlib and SciencePlots: recommended for nicer plotting.

For development, it is recommended to run

python -m pip install -e '.[dev,vis]'

A pinned version of all the requirements is kept in requirements.txt. For a quick install with the versions that are currently being tested on the CI

python -m pip install -r requirements.txt -e .

or use requirements-dev.txt to also install development packages (e.g. ruff).

Documentation

Documentation can be generated using Sphinx. For example, to generate a nice HTML-based variant go

cd docs && make html
xdg-open _build/html/index.html

Sphinx ca can also generate LaTeX documentation with

make latex && cd _build/latex && make
xdg-open pyshocks.pdf

The documentation is also hosted on readthedocs.