From 8fa74f51264e5d7fc6a9f54b3809ef209090be44 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Tue, 20 Jan 2026 14:43:26 -0800 Subject: [PATCH 01/11] Add basic documentation for LLM agents From 820facd28c438f9d2a6cc7af5449a98444490728 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 02/11] Convert .rst files to markdown --- docs/requirements.txt | 1 + docs/source/conf.py | 7 +++ docs/source/{dev_guide.rst => dev_guide.md} | 23 ++++---- docs/source/faq.md | 47 +++++++++++++++ docs/source/faq.rst | 51 ---------------- docs/source/solvers.md | 34 +++++++++++ docs/source/solvers.rst | 12 ---- docs/source/solvers/lpse2d.rst | 44 -------------- docs/source/solvers/lpse2d/overview.md | 35 +++++++++++ docs/source/solvers/vfp1d.rst | 10 ---- docs/source/solvers/vfp1d/overview.md | 7 +++ docs/source/solvers/vlasov1d/overview.md | 56 ++++++++++++++++++ docs/source/solvers/vlasov1d1v.rst | 64 --------------------- docs/source/{tests.rst => tests.md} | 32 +++++------ docs/source/usage.md | 51 ++++++++++++++++ docs/source/usage.rst | 43 -------------- docs/source/usage/initialization.md | 31 ++++++++++ docs/source/usage/initialization.rst | 36 ------------ docs/source/usage/lpse2d.rst | 0 docs/source/usage/tf1d.md | 47 +++++++++++++++ docs/source/usage/tf1d.rst | 49 ---------------- docs/source/usage/vlasov1d.md | 55 ++++++++++++++++++ docs/source/usage/vlasov1d.rst | 60 ------------------- docs/source/usage/vlasov1d2v.md | 60 +++++++++++++++++++ docs/source/usage/vlasov1d2v.rst | 64 --------------------- docs/source/usage/vlasov2d2v.rst | 0 26 files changed, 455 insertions(+), 464 deletions(-) rename docs/source/{dev_guide.rst => dev_guide.md} (91%) create mode 100644 docs/source/faq.md delete mode 100644 docs/source/faq.rst create mode 100644 docs/source/solvers.md delete mode 100644 docs/source/solvers.rst delete mode 100644 docs/source/solvers/lpse2d.rst create mode 100644 docs/source/solvers/lpse2d/overview.md delete mode 100644 docs/source/solvers/vfp1d.rst create mode 100644 docs/source/solvers/vfp1d/overview.md create mode 100644 docs/source/solvers/vlasov1d/overview.md delete mode 100644 docs/source/solvers/vlasov1d1v.rst rename docs/source/{tests.rst => tests.md} (69%) create mode 100644 docs/source/usage.md delete mode 100644 docs/source/usage.rst create mode 100644 docs/source/usage/initialization.md delete mode 100644 docs/source/usage/initialization.rst delete mode 100644 docs/source/usage/lpse2d.rst create mode 100644 docs/source/usage/tf1d.md delete mode 100644 docs/source/usage/tf1d.rst create mode 100644 docs/source/usage/vlasov1d.md delete mode 100644 docs/source/usage/vlasov1d.rst create mode 100644 docs/source/usage/vlasov1d2v.md delete mode 100644 docs/source/usage/vlasov1d2v.rst delete mode 100644 docs/source/usage/vlasov2d2v.rst diff --git a/docs/requirements.txt b/docs/requirements.txt index bb14ef8c..19fdc733 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,3 +5,4 @@ sphinx > 3.0.0 sphinx_copybutton sphinx-rtd-theme >= 1.0, < 2.0 sphinx-github-style >= 1.0, <= 1.1 +myst-parser >= 2.0 diff --git a/docs/source/conf.py b/docs/source/conf.py index f899185b..c8b01427 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,6 +55,13 @@ "sphinx.ext.napoleon", "sphinx_copybutton", "sphinx_github_style", + "myst_parser", +] + +# MyST parser configuration +myst_enable_extensions = [ + "dollarmath", # Enable $...$ and $$...$$ math + "colon_fence", # Enable ::: fenced directives ] # options for sphinx_github_style top_level = "adept" diff --git a/docs/source/dev_guide.rst b/docs/source/dev_guide.md similarity index 91% rename from docs/source/dev_guide.rst rename to docs/source/dev_guide.md index f080e551..0e328762 100644 --- a/docs/source/dev_guide.rst +++ b/docs/source/dev_guide.md @@ -1,18 +1,16 @@ -Developer Guide ---------------- +# Developer Guide -In case you are interested in looking past the forward simulation use case, that is, if you are interested in running a program which is not just +In case you are interested in looking past the forward simulation use case, that is, if you are interested in running a program which is not just: -.. code-block:: bash - - python3 run.py --cfg config// +```bash +python3 run.py --cfg config// +``` This runs a forward simulation with the specified input parameters. It calls functions within `utils/runner.py` for this. -The most important one to understand is the ``_run_`` function. Here is a stripped down pseudo-code version - -.. code-block:: python +The most important one to understand is the `_run_` function. Here is a stripped down pseudo-code version: - def run(cfg: Dict) -> Tuple[Solution, Dict]: +```python +def run(cfg: Dict) -> Tuple[Solution, Dict]: """ This function is the main entry point for running a simulation. It takes a configuration dictionary and returns a ``diffrax.Solution`` object and a dictionary of datasets. @@ -100,10 +98,9 @@ The most important one to understand is the ``_run_`` function. Here is a stripp # fin return result, datasets +``` - -Here, we are heavily relying on two open-source libraries. +Here, we are heavily relying on two open-source libraries: 1. **MLFlow** as an experiment manager to log parameters, metrics, and artifacts - 2. **Diffrax** to solve the ODEs diff --git a/docs/source/faq.md b/docs/source/faq.md new file mode 100644 index 00000000..09ab07ab --- /dev/null +++ b/docs/source/faq.md @@ -0,0 +1,47 @@ +# FAQ + +--- + +**Q. What is novel about ADEPT?** + +ADEPT has the following features that make it a unique tool for plasma physics simulations: + +- Automatic Differentiation (AD) Enabled (thanks to JAX) +- GPU-capable (thanks to XLA) +- Experiment manager enabled (thanks to MLflow) +- Pythonic + +--- + +**Q. What does AD do for us?** + +AD enables the calculation of derivatives of entire simulations, pieces of it, or anything in between. This can be used for: + +- Sensitivity analyses +- Parameter estimation +- Parameter optimization +- Model training + +--- + +**Q. Why use MLflow?** + +MLFlow handles all the incredibly rote metadata management that computational scientists have historically either just completely ignored, written in an excel file, used a lab notebook, etc. (You may always be an exception!) + +You can store parameters (inputs to the simulation, box size, driver parameters, etc.), metrics (run time, total electrostatic energy, temperature at t=200 ps etc.) and artifacts (the fields, distribution functions, plots, post processed quantities, configuration etc.) in a single place. + +This place can either be your local machine, or better yet, a remote server that is backed by a database and an object store. + +--- + +**Q. Why use xarray?** + +Xarray is a great way to handle gridded data. It is performant, has a stable API, has high level plotting features. It is fairly portable, maybe not as much as HDF5, but it is a netCDF4 file so it can't be that bad! + +--- + +**Q. Why use diffrax?** + +Diffrax provides the ODE integrator capabilities. However, you can, and we often do, side-step the actual time-integrator but only use diffrax for yet again, a stable API that enables us to save data in a consistent way. Diffrax lets us pass functions to the integrator, which is a great way to store custom post-processed (e.g. interpolated) quantities. You can also handle the result in the same consistent way. Yes, we could have just designed an API. But diffrax DOES also provide the time integrator. + +Another thing diffrax does is it has a great loop handling system that compiles much faster than anything I have written. I don't know why that is, but it is. diff --git a/docs/source/faq.rst b/docs/source/faq.rst deleted file mode 100644 index f26f4aa6..00000000 --- a/docs/source/faq.rst +++ /dev/null @@ -1,51 +0,0 @@ -FAQ ------ - -Q. **What is novel about ADEPT?** - -A. ADEPT has the following features that make it a unique tool for plasma physics simulations: - -- Automatic Differentiation (AD) Enabled (bc of JAX) -- GPU-capable (bc of XLA) -- Experiment manager enabled (bc of mlflow) -- Pythonic - ---------------------- - -Q. **What does AD do for us?** - -A. AD enables the calculation of derivatives of entire simulations, pieces of it, or anything in between. This can be used for - -- sensitivity analyses -- parameter estimation -- parameter optimization -- model training - ---------------------- - -**Q. Why use MLflow?** - -A. MLFlow handles all the incredibly rote metadata management that computational scientists have historically either just -completely ignored, written in an excel file, used a lab notebook, etc (You may always be an exception!). - -You can store parameters (inputs to the simulation, box size, driver parameters, etc.), metrics (run time, total electrostatic energy, temperature at t=200 ps etc.) -and artifacts (the fields, distribution functions, plots, post processed quantities, configuration etc.) in a single place. - -This place can either be your local machine, or better yet, a remote server that is backed by a database and an object store. - ---------------------- - -**Q. Why use xarray?** - -A. Xarray is a great way to handle gridded data. It is performant, has a stable API, has high level plotting features. It is fairly portable, maybe not as much as HDF5, but it is a netCDF4 file so -it can't be that bad! - ---------------------- - -**Q. Why use diffrax?** - -A. Diffrax provides the ODE integrator capabilities. However, you can, and we often do, side-step the actual time-integrator but only use diffrax for yet again, a stable API that enables us to -save data in a consistent way. Diffrax lets us pass functions to the integrator, which is a great way to store custom post-processed (e.g. interpolated) quantities. You can also handle the result -in the same consistent way. Yes, we could have just designed an API. But diffrax DOES also provide the time integrator. - -Another thing diffrax does is it has a great loop handling system that compiles much faster than anything I have written. I don't know why that is, but it is. diff --git a/docs/source/solvers.md b/docs/source/solvers.md new file mode 100644 index 00000000..468c31af --- /dev/null +++ b/docs/source/solvers.md @@ -0,0 +1,34 @@ +# Available Solvers + +ADEPT provides several solver modules for different plasma physics applications. + +## Kinetic Solvers + +### [Vlasov-1D](solvers/vlasov1d/overview.md) + +1D1V Vlasov-Poisson/Maxwell solver with Fokker-Planck collisions. Ideal for studying electron plasma waves, Landau damping, and wave-particle interactions. + +- [Overview & Equations](solvers/vlasov1d/overview.md) +- [Configuration Reference](solvers/vlasov1d/config.md) + +### [Vlasov-2D](solvers/vlasov2d/overview.md) + +2D2V Vlasov-Maxwell solver for electromagnetic simulations in two spatial dimensions. + +- [Overview & Equations](solvers/vlasov2d/overview.md) +- [Configuration Reference](solvers/vlasov2d/config.md) + +### [VFP-1D](solvers/vfp1d/overview.md) + +Vlasov-Fokker-Planck solver for electron transport over collisional time-scales. + +- [Overview](solvers/vfp1d/overview.md) + +## Envelope Solvers + +### [LPSE-2D (Envelope-2D)](solvers/lpse2d/overview.md) + +2D laser-plasma envelope solver for modeling laser-plasma instabilities including Two-Plasmon Decay (TPD) and Stimulated Raman Scattering (SRS). + +- [Overview & Equations](solvers/lpse2d/overview.md) +- [Configuration Reference](solvers/lpse2d/config.md) diff --git a/docs/source/solvers.rst b/docs/source/solvers.rst deleted file mode 100644 index 5a643da3..00000000 --- a/docs/source/solvers.rst +++ /dev/null @@ -1,12 +0,0 @@ -Available solvers -================== - -The solvers that we have implemented (and documented) so far are - - -.. toctree:: - solvers/vlasov1d1v - solvers/lpse2d - solvers/vfp1d - :maxdepth: 3 - :caption: Implemented solvers: diff --git a/docs/source/solvers/lpse2d.rst b/docs/source/solvers/lpse2d.rst deleted file mode 100644 index fce11e65..00000000 --- a/docs/source/solvers/lpse2d.rst +++ /dev/null @@ -1,44 +0,0 @@ -Enveloped equations in Cartesian 2D -==================================== - - - -Equations and Quantities -------------------------- -These equations model the evolution and interaction of the complex envelopes of light waves and plasma waves. This is faster than modeling the plasma waves using a fluid or kinetic solver along with modeling the light waves - -Note on pump depletion -^^^^^^^^^^^^^^^^^^^^^^^^ -One can solve these equations with or without "pump depletion". "Pump depletion" is the effect of the plasma waves on the light waves. We do not currently have this implemented, so we have light waves that behave as external drivers for the plasma waves and we only model the plasma wave response. -This approach is adequate for modeling laser plasma instabilities below the absolute instability threshold. - -Electron Plasma Waves -^^^^^^^^^^^^^^^^^^^^^^^ - -.. math:: - \nabla \cdot \left[ i \left(\frac{\partial}{\partial t} + \nu_e^{\circ} \right) + \frac{3 v_{te}^2}{2 \omega_{p0}} \nabla^2 + \frac{\omega_{p0}}{2}\left(1-\frac{n_b(x)}{n_0}\right) \right] \textbf{E}_h = S_{TPD} + S_h - - -Two Plasmon Decay -^^^^^^^^^^^^^^^^^^^^ - -.. math:: - S_{\text{TPD}} \equiv \frac{e}{8 \omega_{p0} m_e} \frac{n_b(x)}{n_0} \nabla \cdot [\nabla (\textbf{E}_0 \cdot \textbf{E}_h^*) - \textbf{E}_0 \nabla\cdot \textbf{E}_h^*] e^{-i (\omega_0 - 2 \omega_{p0})t} - -Laser Driver -^^^^^^^^^^^^^^^ -We only have a plane wave implementation for now - -.. math:: - E_0(t, x, y) = \sum_j^{N_c} A_j ~ \exp(-i k_0 x - i \omega_0 \Delta\omega_j ~ t + \phi_j) - - -Configuration Options ----------------------- - -As with all other solvers, the configuration is passed in via a ``yaml`` file. The datamodel for the configuration is documented below - -.. toctree:: - datamodels/lpse2d - :maxdepth: 3 - :caption: Configuration Options: diff --git a/docs/source/solvers/lpse2d/overview.md b/docs/source/solvers/lpse2d/overview.md new file mode 100644 index 00000000..2c5e3945 --- /dev/null +++ b/docs/source/solvers/lpse2d/overview.md @@ -0,0 +1,35 @@ +# LPSE 2D (Envelope-2D) Solver + +## Equations and Quantities + +These equations model the evolution and interaction of the complex envelopes of light waves and plasma waves. This is faster than modeling the plasma waves using a fluid or kinetic solver along with modeling the light waves. + +### Note on Pump Depletion + +One can solve these equations with or without "pump depletion". "Pump depletion" is the effect of the plasma waves on the light waves. We do not currently have this implemented, so we have light waves that behave as external drivers for the plasma waves and we only model the plasma wave response. + +This approach is adequate for modeling laser plasma instabilities below the absolute instability threshold. + +### Electron Plasma Waves + +$$ +\nabla \cdot \left[ i \left(\frac{\partial}{\partial t} + \nu_e^{\circ} \right) + \frac{3 v_{te}^2}{2 \omega_{p0}} \nabla^2 + \frac{\omega_{p0}}{2}\left(1-\frac{n_b(x)}{n_0}\right) \right] \textbf{E}_h = S_{TPD} + S_h +$$ + +### Two Plasmon Decay + +$$ +S_{\text{TPD}} \equiv \frac{e}{8 \omega_{p0} m_e} \frac{n_b(x)}{n_0} \nabla \cdot [\nabla (\textbf{E}_0 \cdot \textbf{E}_h^*) - \textbf{E}_0 \nabla\cdot \textbf{E}_h^*] e^{-i (\omega_0 - 2 \omega_{p0})t} +$$ + +### Laser Driver + +We only have a plane wave implementation for now: + +$$ +E_0(t, x, y) = \sum_j^{N_c} A_j ~ \exp(-i k_0 x - i \omega_0 \Delta\omega_j ~ t + \phi_j) +$$ + +## Configuration Reference + +See the [Configuration Reference](config.md) for complete YAML schema documentation. diff --git a/docs/source/solvers/vfp1d.rst b/docs/source/solvers/vfp1d.rst deleted file mode 100644 index f2e1497e..00000000 --- a/docs/source/solvers/vfp1d.rst +++ /dev/null @@ -1,10 +0,0 @@ -Implicit Cartesian-Spherical Harmonics Vlasov-Fokker-Planck in 1D3V -===================================================================== - -This set of solvers is usually used to model electron transport over hydrodynamic / collisional time-scales while the other Vlasov solvers in ``ADEPT`` are for -modeling over electron plasma wave time-scales. - -Equations and Quantities -------------------------- - -TODO diff --git a/docs/source/solvers/vfp1d/overview.md b/docs/source/solvers/vfp1d/overview.md new file mode 100644 index 00000000..20a61017 --- /dev/null +++ b/docs/source/solvers/vfp1d/overview.md @@ -0,0 +1,7 @@ +# Vlasov-Fokker-Planck 1D3V Solver + +This set of solvers is usually used to model electron transport over hydrodynamic / collisional time-scales while the other Vlasov solvers in ADEPT are for modeling over electron plasma wave time-scales. + +## Equations and Quantities + +*TODO: Documentation in progress.* diff --git a/docs/source/solvers/vlasov1d/overview.md b/docs/source/solvers/vlasov1d/overview.md new file mode 100644 index 00000000..692011d3 --- /dev/null +++ b/docs/source/solvers/vlasov1d/overview.md @@ -0,0 +1,56 @@ +# Vlasov 1D1V Solver + +## Equations and Quantities + +We solve the following coupled set of partial differential equations: + +$$ +\frac{\partial f}{\partial t} + v \frac{\partial f}{\partial x} + \frac{q}{m} (E + E_D) \frac{\partial f}{\partial v} = \nu \partial_v (v f + v_0^2 \partial_v f) +$$ + +$$ +\partial_x E = 1 - \int f \, dv +$$ + +where $f$ is the distribution function, $E$ is the electric field, $C(f)$ is the collision operator, $q$ is the charge, $m$ is the mass, and $v$ is the velocity. + +The distribution function is $f = f(t, x, v)$ and the electric field is $E = E(t, x)$. + +These simulations can be initialized via perturbing the distribution function or the electric field. +The electric field can be "driven" using $E_D$ which is a user defined function of time and space. + +## Solver Options + +As with all other solvers, the configuration is passed in via a `yaml` file. Below we describe the key solver options, and then link to the full configuration reference. + +### Velocity Advection + +1. **`exponential`** - This solver (incorrectly) assumes periodic boundaries in the velocity direction and uses a direct exponential solve such that + +$$ +f^{n+1} = f^n \times \exp(A \cdot dt) +$$ + +where $A$ is the advection operator. This is a much faster solver than the cubic-spline solver, but is less accurate. Use this if you are confident that the distribution function will be well behaved in the tails. + +2. **`cubic-spline`** - This is a semi-Lagrangian solver that uses a cubic-spline interpolator to advect the distribution function in velocity space. Use this if you have trouble with the exponential solver. + +### Spatial Advection + +1. **`exponential`** - This is the only solver that is available. We only have periodic boundaries implemented in space (for the plasma) so this is perfectly fine. It is also very fast. + +### Field Solver + +1. **`poisson`** - This is the standard spectral Poisson solver. This is the fastest and most accurate solver available. +2. **`hampere`** - This solver uses a Hamiltonian formulation of the Vlasov-Ampere system that conserves energy exactly. This is the 2nd most reliable solver. +3. **`ampere`** - This solver uses Ampere's law to solve for the electric field. + +### Collisions + +1. **`none`** - No collisions are included in the simulation. +2. **`lenard-bernstein`** - This solver uses the Lenard-Bernstein collision operator to include collisions in the simulation. +3. **`dougherty`** - This solver uses the Dougherty collision operator to include collisions in the simulation. + +## Configuration Reference + +See the [Configuration Reference](config.md) for complete YAML schema documentation. diff --git a/docs/source/solvers/vlasov1d1v.rst b/docs/source/solvers/vlasov1d1v.rst deleted file mode 100644 index 2a08eb99..00000000 --- a/docs/source/solvers/vlasov1d1v.rst +++ /dev/null @@ -1,64 +0,0 @@ -Explicit Cartesian-Cartesian Vlasov 1D1V -========================================= - -Equations and Quantities -------------------------- -We solve the following coupled set of partial differential equations - -.. math:: - \frac{\partial f}{\partial t} + v \frac{\partial f}{\partial x} + \frac{q}{m} (E + E_D) \frac{\partial f}{\partial v} &= \nu \partial_v (v f + v_0^2 \partial_v f) - - \partial_x E &= 1 - \int f dv - -where :math:`f` is the distribution function, :math:`E` is the electric field, :math:`C(f)` is the collision operator, :math:`q` is the charge, :math:`m` is the mass, and :math:`v` is the velocity. - -The distribution function is :math:`f = f(t, x, v)` and the electric field is :math:`E = E(t, x)` - -These simulations can be initialized via perturbing the distribution function or the electric field. -The electric field can be "driven" using :math:`E_D` which is a user defined function of time and space. - -Configuration Options ----------------------- - -As with all other solvers, the configuration is passed in via a ``yaml`` file. The datamodel for the configuration is defined in the documentation but most will first care about -how the equations themselves are solved and what the different options are. We list those first here. - -Velocity advection -^^^^^^^^^^^^^^^^^^^^^^^^ -1. ``exponential`` - This solver (incorrectly) assumes periodic boundaries in the velocity direction and uses a direct exponential solve such that - -.. math:: - f^{n+1} = f^n \times \exp(A*dt) - -where :math:`A` is the advection operator. This is a much faster solver than the cubic-spline solver, but is less accurate. Use this if you are confident that the distribution function will be well behaved in the tails - -2. ``cubic-spline`` - This is a semi-Lagrangian solver that uses a cubic-spline interpolator to advect the distribution function in velocity space. Use this if you have trouble with the exponential solver. - - -Spatial advection -^^^^^^^^^^^^^^^^^^^^^^^^ -1. ``exponential`` - This is the only solver that is available. We only have periodic boundaries implemented in space (for the plasma) so this is perfectly fine. It is also very fast. - - -Field solver -^^^^^^^^^^^^^^^^^^^^^^^^ - -1. ``poisson`` - This is the only field solver that is available. It uses a spectral solver to solve the Poisson equation. This is the fastest and most accurate solver available. -2. ``hampere`` - This solver uses a Hamiltonian formulation of the Vlasov-Ampere system that conserves energy exactly. This is the 2nd most reliable solver. -3. ``ampere`` - This solver uses the Ampere's law to solve for the electric field. - -Collisions -^^^^^^^^^^^^^^^^^^^^^^^^ -1. ``none`` - No collisions are included in the simulation -2. ``lenard-bernstein`` - This solver uses the Lenard-Bernstein collision operator to include collisions in the simulation. -3. ``daugherty`` - This solver uses the Daugherty collision operator to include collisions in the simulation. - - -Remaining Options -^^^^^^^^^^^^^^^^^^^^^^^^ -The following pages document the configuration options for the Vlasov1D1V solver - -.. toctree:: - datamodels/vlasov1d - :maxdepth: 3 - :caption: Configuration Options: diff --git a/docs/source/tests.rst b/docs/source/tests.md similarity index 69% rename from docs/source/tests.rst rename to docs/source/tests.md index 48ac4821..07b4baa0 100644 --- a/docs/source/tests.rst +++ b/docs/source/tests.md @@ -1,33 +1,29 @@ -Tests -============= +# Tests -Run tests and examples ------------------------------- -First install pytest via +## Run Tests and Examples -.. code-block:: console +First install pytest via: - (venv) $ pip install pytest - (venv) $ pytest +```bash +pip install pytest +pytest +``` This will run all the tests, which will likely include relatively expensive 2D2V Vlasov simulations. If you only want to see example usage, you can choose particular tests by using the `-k` flag. -The package is tested against +## Test Suite -1D1V Vlasov implementation --------------------------------- -- `test_landau_damping.py` - recover the real part and imaginary part (Landau damping) of the resoance according to the kinetic dispersion relation -- `test_absorbing_wave.py` - make sure the absorbing boundary conditions for the wave solver for the vector potential work correctly +The package is tested against: +### 1D1V Vlasov Implementation -1D two-fluid implementation --------------------------------- +- `test_landau_damping.py` - recover the real part and imaginary part (Landau damping) of the resonance according to the kinetic dispersion relation +- `test_absorbing_wave.py` - make sure the absorbing boundary conditions for the wave solver for the vector potential work correctly -- `test_resonance.py` - recover the Bohm-Gross dispersion relation and kinetic dispersion relation just using the forward pass +### 1D Two-Fluid Implementation +- `test_resonance.py` - recover the Bohm-Gross dispersion relation and kinetic dispersion relation just using the forward pass - `test_resonance_search.py` - recover the Bohm-Gross dispersion relation and kinetic dispersion relation using the backward pass - - `test_landau_damping.py` - recover the Landau damping rate according to the kinetic dispersion relation using a phenomenological term - - `test_against_vlasov.py` - recover a driven warm plasma wave simulation that is nearly identical to a Vlasov-Boltzmann simulation diff --git a/docs/source/usage.md b/docs/source/usage.md new file mode 100644 index 00000000..152c7447 --- /dev/null +++ b/docs/source/usage.md @@ -0,0 +1,51 @@ +# Usage + +## Installation + +To use ADEPT, first install the requirements using pip: + +```bash +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt +``` + +or using conda: + +```bash +mamba env create -f env.yaml +mamba activate adept +``` + +--- + +## Run an Example + +The most common use case for ADEPT is a simple forward simulation that can be run from the command line. For example, to run a 1D1V Vlasov simulation of a driven electron plasma wave: + +```bash +python3 run.py --cfg configs/vlasov-1d/epw +``` + +The input parameters are provided in `configs/vlasov-1d/epw.yaml`. + +### Access the Output + +The output will be saved and made accessible via MLFlow. To access it: + +1. Launch an mlflow server via running `mlflow ui` from the command line +2. Open a web browser and navigate to http://localhost:5000 +3. Click on the experiment name to see the results + +--- + +## Solver-Specific Guides + +```{toctree} +:maxdepth: 2 + +usage/initialization +usage/vlasov1d +usage/vlasov1d2v +usage/tf1d +``` diff --git a/docs/source/usage.rst b/docs/source/usage.rst deleted file mode 100644 index f89c99fa..00000000 --- a/docs/source/usage.rst +++ /dev/null @@ -1,43 +0,0 @@ -Usage -===== - -Installation ------------- - -To use adept, first install the requirements using pip: - -.. code-block:: console - - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ pip install -r requirements.txt - -or using conda: - -.. code-block:: console - - $ mamba env create -f env.yaml - $ mamba activate adept - (adept) $ - --------------- - - -Run an example --------------- - -The most common and obvious use case for ADEPT is a simple forward simulation that can be run from the command line. For example, to run a 1D1V Vlasov simulation of a driven electron plasma wave, use the following command: - -.. code-block:: bash - - (venv) $ python3 run.py --cfg configs/vlasov-1d/epw - -The input parameters are provided in `configs/vlasov-1d/epw.yaml`. - -**Access the output** - -The output will be saved and made accessible via MLFlow. To access it, - -1. Launch an mlflow server via running ``mlflow ui`` from the command line -2. Open a web browser and navigate to http://localhost:5000 -3. Click on the experiment name to see the results diff --git a/docs/source/usage/initialization.md b/docs/source/usage/initialization.md new file mode 100644 index 00000000..938433a2 --- /dev/null +++ b/docs/source/usage/initialization.md @@ -0,0 +1,31 @@ +# The Tanh Profile + +This profile is used for spatial and temporal envelopes everywhere in this code. + +This is different per simulation type but there are some consistent concepts. These are that the density can be defined as a function of space, the driver (antenna or ponderomotive) can be a function of time and space, and the collision frequency can be a function of time and space. + +That is, you can specify: + +$$ +n(x), \quad E(t, x), \quad \nu(t, x) +$$ + +Each of these profiles is provided using a tanh function that is parameterized using: + +- `p_wL`, `p_wR` - the rise and fall of the flat-top +- `p_w` - width of the flat-top +- `p_c` - center of the flat-top +- `p_L = p_c - p_w / 2` - left edge of the flat-top +- `p_R = p_c + p_w / 2` - right edge of the flat-top + +where `p` can be the time or space coordinate depending on the context. + +Then, the overall shape is given by: + +$$ +f(p) = 0.5 \times \left[ \tanh\left(\frac{ax - p_L}{p_{wL}}\right) - \tanh\left(\frac{ax - p_R}{p_{wR}}\right) \right] +$$ + +where `ax` is the time or space axis. + +If you plot this, it looks like a flat top centered at `p_c` with width `p_w`, and a rise and fall of `p_wL` and `p_wR` respectively. diff --git a/docs/source/usage/initialization.rst b/docs/source/usage/initialization.rst deleted file mode 100644 index be56914b..00000000 --- a/docs/source/usage/initialization.rst +++ /dev/null @@ -1,36 +0,0 @@ -The Tanh profile ------------------------ - -This profile is used for spatial and temporal envelopes everywhere in this code. - -This is different per simulation type but there are some consistent concepts. These are that the density can be defined -as a function of space, the driver (antenna or ponderomotive) can be a function of time and space, and the collision frequency -can be a function of time and space. - -That is, you can specify, - -.. math:: - n(x), E(t, x), \nu(t, x) - -Each of these profiles is provided using a tanh function that is parameterized using - -``p_{wL}``, ``p_{wR}`` - the rise and fall of the flat-top - -``p_w`` - width of the flat-top - -``p_c`` - center of the flat-top - -``p_L = p_c - p_w / 2`` - left edge of the flat-top - -``p_R = p_c + p_w / 2`` - right edge of the flat-top - -where p can be the time or space coordinate depending on the context - -Then, the overall shape is given by - -.. math:: - f(p) = 0.5 * \tanh((ax - p_L) / p_{wL}) - \tanh((ax - p_R) / p_{wR}) - -where ``ax`` is the time or space axis - -If you plot this, it looks like a flat top centered at ``p_c`` and has a width ``p_w``, and a rise and fall of ``p_{wL}`` and ``p_{wR}`` respectively. diff --git a/docs/source/usage/lpse2d.rst b/docs/source/usage/lpse2d.rst deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/source/usage/tf1d.md b/docs/source/usage/tf1d.md new file mode 100644 index 00000000..9287b541 --- /dev/null +++ b/docs/source/usage/tf1d.md @@ -0,0 +1,47 @@ +# Fluid-Poisson 1D + +To run the code for TwoFluid-Poisson 1D, use the configs in `configs/tf-1d/`. +There is a `mode` option in the config file which tells ADEPT which solver to use. + +## Equations + +```{note} +Work in progress +``` + +The normalized 1D Fluid-Poisson system is given by: + +$$ +\partial_t n_e + \partial_x (n_e u_e) = 0 +$$ + +$$ +\partial_t u_e + u_e \partial_x u_e = -\frac{\partial_x P_e}{n_e} - \frac{E}{n_e} +$$ + +$$ +\partial_x^2 E = n_i - n_e +$$ + +The ions are static but all the functionality is in place if someone wants to get them to move! + +## Things You Might Care About + +1. Infinite length (Single mode) plasma waves (Landau damping, trapping) +2. Finite length plasma waves (everything in 1. + Wavepackets) +3. Wave dynamics on density gradients (2 + density gradients) +4. Machine-learned fluid closures + +--- + +## Configuration Options + +### Density Profile + +Uniform is easy. For a non-uniform profile, you have to specify the parameters of the profile. + +The density profile can be parameterized as a sinusoidal perturbation or a tanh flat top. See [initialization](initialization.md) for details on the tanh flat-top parameters. + +### Ponderomotive Driver + +You may want a driver to drive up a wave. The envelope for this wave is specified via a tanh profile in space and in time. The other parameters to the wave are the wavenumber, frequency, amplitude, and so on. Refer to the config file for more details. diff --git a/docs/source/usage/tf1d.rst b/docs/source/usage/tf1d.rst deleted file mode 100644 index 62735ef5..00000000 --- a/docs/source/usage/tf1d.rst +++ /dev/null @@ -1,49 +0,0 @@ -Fluid-Poisson 1D -======================= - -To run the code for TwoFluid-Poisson 1D, use the configs in `configs/tf-1d/`. -There is a `mode` option in the config file which tells `ADEPT` which solver to use. - -The normalized 1D Fluid-Poisson system is given by: - -.. note:: - - Work in progress - -.. math:: - - \partial_t n_e + \partial_x (n_e u_e) = 0 - - \partial_t u_e + u_e \partial_x u_e = -\frac{\partial_x P_e}{n_e} - \frac{E}{n_e} - - \partial_x^2 E = n_i - n_e - -The ions are static but all the functionality is in place if someone wants to get them to move! - -**Things you might care about** - -1. Infinite length (Single mode) plasma waves (Landau damping, trapping) - -2. Finite length plasma waves (everything in 1. + Wavepackets) - -3. Wave dynamics on density gradients (2 + density gradients) - -4. Machine-learned fluid closures - - ------------------------ - - -Things you can change in the config file ----------------------------------------------- - -Density profile -^^^^^^^^^^^^^^^ -Uniform is easy. For a non-uniform profile, you have to specify the parameters of the profile. - -The density profile can be parameterized as a sinusoidal perturbation or a tanh flat top. The parameters to the tanh flat-top are referred to in - -Ponderomotive Driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You may want to a driver to drive up a wave. The envelope for this wave is specified via a tanh profile in space and in time. The other parameters to the wave -are the wavenumber, frequency, amplitude, and so on. Refer to the config file for more details diff --git a/docs/source/usage/vlasov1d.md b/docs/source/usage/vlasov1d.md new file mode 100644 index 00000000..d2e1e9ae --- /dev/null +++ b/docs/source/usage/vlasov1d.md @@ -0,0 +1,55 @@ +# Vlasov-Poisson-Fokker-Planck 1D1V + +To run the code for Vlasov-Poisson 1D1V, use the configs in `configs/vlasov1d/`. +There is a `mode` option in the config file which tells ADEPT which solver to use. + +## Equations + +The normalized 1D1V Vlasov-Poisson-Fokker-Planck system is given by: + +$$ +\frac{\partial f}{\partial t} + v \frac{\partial f}{\partial x} + E \frac{\partial f}{\partial v} = C_{ee}(f) + C_{K}(f) +$$ + +$$ +\partial_x^2 E = 1 - \int f \, dv +$$ + +$$ +C_{ee}(f) = \nu_{ee} \frac{\partial}{\partial v} \left( v f + v_{th}^2 \partial_v f \right) +$$ + +$$ +C_K(f) = \nu_K (f - f_{Mx}) +$$ + +The ions are static but an enterprising individual should be able to reuse the electron code for the ions. + +## Things You Might Care About + +1. Infinite length (Single mode) plasma waves (Landau damping, trapping) +2. Finite length plasma waves (everything in 1. + Wavepackets) +3. Wave dynamics on density gradients (2 + density gradients) +4. Stimulated Raman Scattering (3 + light waves) + +--- + +## Configuration Options + +### Density Profile + +Uniform is easy. For a non-uniform profile, you have to specify the parameters of the profile. + +The density profile can be parameterized as a sinusoidal perturbation or a tanh flat top. See [initialization](initialization.md) for details on the tanh flat-top parameters. + +### Ponderomotive Driver + +You may want a driver to drive up a wave. The envelope for this wave is specified via a tanh profile in space and in time. The other parameters to the wave are the wavenumber, frequency, amplitude, and so on. Refer to the config file for more details. + +### Collision Frequency + +What is `nu_ee`? It will modify the dynamics of the problem, possibly substantially depending on the distribution function dynamics. The envelope for this can also be specified in the same way as the driver. + +### Krook Frequency + +This is another dissipative operator but in terms of physical correspondence, this mostly just resembles sideloss if anything. Use this as a hard thermalization operator, say for boundaries as in the SRS example. diff --git a/docs/source/usage/vlasov1d.rst b/docs/source/usage/vlasov1d.rst deleted file mode 100644 index 40cd55ab..00000000 --- a/docs/source/usage/vlasov1d.rst +++ /dev/null @@ -1,60 +0,0 @@ -Vlasov-Poisson-Fokker-Planck 1D1V -==================================== - -To run the code for Vlasov-Poisson 1D1V, use the configs in `configs/vlasov1d/`. -There is a `mode` option in the config file which tells `ADEPT` which solver to use. - -The normalized 1D1V Vlasov-Poisson-Fokker-Planck system is given by: - -.. math:: - - \frac{\partial f}{\partial t} + v \frac{\partial f}{\partial x} + - E \frac{\partial f}{\partial v} = C_{ee}(f) + C_{K}(f) - - \partial_x^2 E = 1 - \int f dv - - C_{ee}(f) = \nu_{ee} \frac{\partial}{\partial v} - \left( v f + v_{th}^2 \partial_v f \right) - - C_K(f) = \nu_K (f - f_{Mx}) - -The ions are static but an enterprising individual should be able to reuse the electron code for the ions - -**Things you might care about** - -1. Infinite length (Single mode) plasma waves (Landau damping, trapping) - -2. Finite length plasma waves (everything in 1. + Wavepackets) - -3. Wave dynamics on density gradients (2 + density gradients) - -4. Stimulated Raman Scattering (3 + light waves) - - ------------------------ - - -Things you can change in the config file ----------------------------------------------- - -Density profile -^^^^^^^^^^^^^^^ -Uniform is easy. For a non-uniform profile, you have to specify the parameters of the profile. - -The density profile can be parameterized as a sinusoidal perturbation or a tanh flat top. The parameters to the tanh flat-top are referred to in - -Ponderomotive Driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You may want to a driver to drive up a wave. The envelope for this wave is specified via a tanh profile in space and in time. The other parameters to the wave -are the wavenumber, frequency, amplitude, and so on. Refer to the config file for more details - -Collision frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -What is ``nu_ee``? It will modify the dynamics of the problem, possibly substantially depending on the distribution function dynamics. The envelope for this can also be specified -in the same way as the driver. - -Krook frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This is another dissipative operator but in terms of physical correspondance, this mostly just resembles sideloss if anything. Use this as a hard thermalization operator, say for boundaries -as in the SRS example. diff --git a/docs/source/usage/vlasov1d2v.md b/docs/source/usage/vlasov1d2v.md new file mode 100644 index 00000000..b168c5b5 --- /dev/null +++ b/docs/source/usage/vlasov1d2v.md @@ -0,0 +1,60 @@ +# Vlasov-Poisson-Fokker-Planck 1D2V + +To run the code for Vlasov-Poisson 1D2V, use the configs in `configs/vlasov1d/`. +There is a `mode` option in the config file which tells ADEPT which solver to use. + +## Equations + +The normalized 1D2V Vlasov-Poisson-Fokker-Planck system is given by: + +$$ +\frac{\partial f}{\partial t} + v_x \frac{\partial f}{\partial x} + E_x \frac{\partial f}{\partial v_x} = C_{ee}(f) + C_{K}(f) +$$ + +$$ +\partial_x^2 E = 1 - \int f \, dv +$$ + +where the collision operators are: + +$$ +C_{ee}(f) = \nu_{ee} \frac{\partial}{\partial \mathbf{v}} \cdot \left( \mathbf{v} f + v_{th}^2 \partial_\mathbf{v} f \right) +$$ + +$$ +C_{ei}(f) = \nu_{ei}(v) \left[\partial_{v_x} \left(-v_y^2 \partial_{v_x} f + v_x v_y \partial_{v_y} f\right) + \partial_{v_y} \left(v_x v_y \partial_{v_x} f - v_x^2 \partial_{v_y} f\right)\right] +$$ + +$$ +C_K(f) = \nu_K (f - f_{Mx}) +$$ + +The ions are static but an enterprising individual should be able to reuse the electron code for the ions. + +## Things You Might Care About + +1. Infinite length (Single mode) plasma waves (Landau damping, trapping) +2. Finite length plasma waves (everything in 1. + Wavepackets) +3. Wave dynamics on density gradients (2 + density gradients) + +--- + +## Configuration Options + +### Density Profile + +Uniform is easy. For a non-uniform profile, you have to specify the parameters of the profile. + +The density profile can be parameterized as a sinusoidal perturbation or a tanh flat top. See [initialization](initialization.md) for details on the tanh flat-top parameters. + +### Ponderomotive Driver + +You may want a driver to drive up a wave. The envelope for this wave is specified via a tanh profile in space and in time. The other parameters to the wave are the wavenumber, frequency, amplitude, and so on. Refer to the config file for more details. + +### Collision Frequency + +What are `nu_ee` and `nu_ei`? They will modify the dynamics of the problem, possibly substantially depending on the distribution function dynamics. The envelope for this can also be specified in the same way as the driver. + +### Krook Frequency + +This is another dissipative operator but in terms of physical correspondence, this mostly just resembles sideloss if anything. Use this as a hard thermalization operator, say for boundaries as in the SRS example. diff --git a/docs/source/usage/vlasov1d2v.rst b/docs/source/usage/vlasov1d2v.rst deleted file mode 100644 index f126aafe..00000000 --- a/docs/source/usage/vlasov1d2v.rst +++ /dev/null @@ -1,64 +0,0 @@ -Vlasov-Poisson-Fokker-Planck 1D2V -=================================== - -To run the code for Vlasov-Poisson 1D2V, use the configs in `configs/vlasov1d/`. -There is a `mode` option in the config file which tells `ADEPT` which solver to use. - -The normalized 1D2V Vlasov-Poisson-Fokker-Planck system is given by: - -.. math:: - - \frac{\partial f}{\partial t} + v_x \frac{\partial f}{\partial x} + - E_x \frac{\partial f}{\partial v_x} = C_{ee}(f) + C_{K}(f) - - \partial_x^2 E = 1 - \int f dv - -where the collision operators are - -.. math:: - - C_{ee}(f) = \nu_{ee} \frac{\partial}{\partial \mathbf{v}} \cdot - \left( \mathbf{v} f + v_{th}^2 \partial_\mathbf{v} f \right) - - C_{ei}(f) = \nu_{ei}(v) \left[\partial_{v_x} \left(-v_y^2 \partial_{v_x} f + v_x v_y \partial_{v_y} f\right) + \partial_{v_y} \left(v_x v_y \partial_{v_x} f - v_x^2 \partial_{v_y} f\right)\right] - - C_K(f) = \nu_K (f - f_{Mx}) - -The ions are static but an enterprising individual should be able to reuse the electron code for the ions - -**Things you might care about** - -1. Infinite length (Single mode) plasma waves (Landau damping, trapping) - -2. Finite length plasma waves (everything in 1. + Wavepackets) - -3. Wave dynamics on density gradients (2 + density gradients) - - ------------------------ - - -Things you can change in the config file ----------------------------------------------- - -Density profile -^^^^^^^^^^^^^^^ -Uniform is easy. For a non-uniform profile, you have to specify the parameters of the profile. - -The density profile can be parameterized as a sinusoidal perturbation or a tanh flat top. The parameters to the tanh flat-top are referred to in - -Ponderomotive Driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You may want to a driver to drive up a wave. The envelope for this wave is specified via a tanh profile in space and in time. The other parameters to the wave -are the wavenumber, frequency, amplitude, and so on. Refer to the config file for more details - -Collision frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -What are ``nu_ee`` and ``nu_ei``? It will modify the dynamics of the problem, possibly substantially depending on the distribution function dynamics. The envelope for this can also be specified -in the same way as the driver. - -Krook frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This is another dissipative operator but in terms of physical correspondance, this mostly just resembles sideloss if anything. Use this as a hard thermalization operator, say for boundaries -as in the SRS example. diff --git a/docs/source/usage/vlasov2d2v.rst b/docs/source/usage/vlasov2d2v.rst deleted file mode 100644 index e69de29b..00000000 From 44a9084fadf28f484a98ca25a24f0331078a86dd Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 03/11] Delete datamodels/ files --- docs/source/solvers/datamodels/lpse2d.rst | 41 --------------------- docs/source/solvers/datamodels/vlasov1d.rst | 41 --------------------- 2 files changed, 82 deletions(-) delete mode 100644 docs/source/solvers/datamodels/lpse2d.rst delete mode 100644 docs/source/solvers/datamodels/vlasov1d.rst diff --git a/docs/source/solvers/datamodels/lpse2d.rst b/docs/source/solvers/datamodels/lpse2d.rst deleted file mode 100644 index 9ea18015..00000000 --- a/docs/source/solvers/datamodels/lpse2d.rst +++ /dev/null @@ -1,41 +0,0 @@ -Configuration Options -====================== -``ADEPT`` needs a ``yaml`` file with the following datamodel to run the simulation. The datamodel is defined in the following class. - -.. autoclass:: adept._lpse2d.datamodel.ConfigModel - :members: __init__ - -Each of the objects used to initialize this datamodel can be treated just like dictionaries. Each dictionary needs to be compiled into a megadictionary that is passed to the solver. -The ``yaml`` configs accomplish this because a ``yaml`` is also a nested dictionary. The following documents those classes - -High Level ------------ -These are the high level configuration options for the LPSE2D solver. Each of these either contains a fundamental type such as -``bool``, ``int``, ``float``, or ``str`` or is another nested ``datamodel`` which can be treated just like a dictionary. - -.. autoclass:: adept._lpse2d.datamodel.UnitsModel - :members: __init__ - -.. autoclass:: adept._lpse2d.datamodel.DensityModel - :members: __init__ - -.. autoclass:: adept._lpse2d.datamodel.GridModel - :members: __init__ - -.. autoclass:: adept._lpse2d.datamodel.SaveModel - :members: __init__ - -.. autoclass:: adept._lpse2d.datamodel.MLFlowModel - :members: __init__ - -.. autoclass:: adept._lpse2d.datamodel.DriverModel - :members: __init__ - -.. autoclass:: adept._lpse2d.datamodel.TermsModel - :members: __init__ - - -Low Level ----------- - -The documentation for the nested datamodels is still TBD. To investigate them further, go to the source code. diff --git a/docs/source/solvers/datamodels/vlasov1d.rst b/docs/source/solvers/datamodels/vlasov1d.rst deleted file mode 100644 index f30ac929..00000000 --- a/docs/source/solvers/datamodels/vlasov1d.rst +++ /dev/null @@ -1,41 +0,0 @@ -Configuration Options -====================== -``ADEPT`` needs a ``yaml`` file with the following datamodel to run the simulation. The datamodel is defined in the following class. - -.. autoclass:: adept._vlasov1d.datamodel.ConfigModel - :members: __init__ - -Each of the objects used to initialize this datamodel can be treated just like dictionaries. Each dictionary needs to be compiled into a megadictionary that is passed to the solver. -The ``yaml`` configs accomplish this because a ``yaml`` is also a nested dictionary. The following documents those classes - -High Level ------------ -These are the high level configuration options for the Vlasov1D solver. Each of these either contains a fundamental type such as -``bool``, ``int``, ``float``, or ``str`` or is another nested ``datamodel`` which can be treated just like a dictionary. - -.. autoclass:: adept._vlasov1d.datamodel.UnitsModel - :members: __init__ - -.. autoclass:: adept._vlasov1d.datamodel.DensityModel - :members: __init__ - -.. autoclass:: adept._vlasov1d.datamodel.GridModel - :members: __init__ - -.. autoclass:: adept._vlasov1d.datamodel.SaveModel - :members: __init__ - -.. autoclass:: adept._vlasov1d.datamodel.MLFlowModel - :members: __init__ - -.. autoclass:: adept._vlasov1d.datamodel.DriverModel - :members: __init__ - -.. autoclass:: adept._vlasov1d.datamodel.TermsModel - :members: __init__ - - -Low Level ----------- - -The documentation for the nested datamodels is still TBD. To investigate them further, go to the source code. From aea844a4444d4da21532ff099794e0f164f6b3b4 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 04/11] Add overview of vlasov2d solver --- docs/source/solvers/vlasov2d/overview.md | 26 ++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/source/solvers/vlasov2d/overview.md diff --git a/docs/source/solvers/vlasov2d/overview.md b/docs/source/solvers/vlasov2d/overview.md new file mode 100644 index 00000000..4f9ea0be --- /dev/null +++ b/docs/source/solvers/vlasov2d/overview.md @@ -0,0 +1,26 @@ +# Vlasov 2D2V Solver + +## Overview + +The Vlasov 2D2V solver evolves the electron distribution function $f(t, x, y, v_x, v_y)$ in a 2D spatial domain with 2D velocity space. This solver supports electromagnetic simulations with self-consistent field evolution. + +## Equations + +We solve the Vlasov-Maxwell system: + +$$ +\frac{\partial f}{\partial t} + \mathbf{v} \cdot \nabla_x f + \frac{q}{m} (\mathbf{E} + \mathbf{v} \times \mathbf{B}) \cdot \nabla_v f = 0 +$$ + +coupled with Maxwell's equations for the electromagnetic fields. + +## Key Features + +- 2D2V phase space (2 spatial dimensions, 2 velocity dimensions) +- Hamiltonian charge-conserving Maxwell solver +- Exponential integrators for spatial and velocity advection +- Support for external electromagnetic drivers + +## Configuration Reference + +See the [Configuration Reference](config.md) for complete YAML schema documentation. From b1f24f488bc969b84d3e87c6b222d05abc551043 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 05/11] Move solver config files to subdirectories --- docs/{lpse2d.md => source/solvers/lpse2d/config.md} | 0 docs/{vlasov1d.md => source/solvers/vlasov1d/config.md} | 0 docs/{vlasov2d.md => source/solvers/vlasov2d/config.md} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename docs/{lpse2d.md => source/solvers/lpse2d/config.md} (100%) rename docs/{vlasov1d.md => source/solvers/vlasov1d/config.md} (100%) rename docs/{vlasov2d.md => source/solvers/vlasov2d/config.md} (100%) diff --git a/docs/lpse2d.md b/docs/source/solvers/lpse2d/config.md similarity index 100% rename from docs/lpse2d.md rename to docs/source/solvers/lpse2d/config.md diff --git a/docs/vlasov1d.md b/docs/source/solvers/vlasov1d/config.md similarity index 100% rename from docs/vlasov1d.md rename to docs/source/solvers/vlasov1d/config.md diff --git a/docs/vlasov2d.md b/docs/source/solvers/vlasov2d/config.md similarity index 100% rename from docs/vlasov2d.md rename to docs/source/solvers/vlasov2d/config.md From f544390958edb6950275c3e8353128b06866def4 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 06/11] Github workflow for building github pages site --- .github/workflows/docs.yaml | 53 +++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..9b17fa3a --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,53 @@ +name: Deploy Documentation + +on: + push: + branches: [main, jack-gh-pages] + paths: + - 'docs/**' + - '.github/workflows/docs.yaml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install -r docs/requirements.txt + + - name: Build Sphinx docs + run: | + cd docs + make html + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From a04bb4d3e1a18893d4a95001c97446ece24b350c Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 07/11] Use uv in github workflow --- .github/workflows/docs.yaml | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9b17fa3a..3929b5b4 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -23,18 +23,11 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: '3.11' - - - name: Install dependencies - run: | - pip install -r docs/requirements.txt + - uses: astral-sh/setup-uv@v5 - name: Build Sphinx docs run: | - cd docs - make html + uv run --with-requirements docs/requirements.txt make -C docs html - name: Upload artifact uses: actions/upload-pages-artifact@v3 From 32bcc6defa1f5fa4cbf2568b0e2a24bf209d6e5d Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 11:42:39 -0800 Subject: [PATCH 08/11] Fix top-level docs index --- docs/ARCHITECTURE.md | 9 +++++++++ docs/RUNNING_A_SIM.md | 8 +++++--- docs/requirements.txt | 2 -- docs/source/index.rst | 43 +++++++++++++++++++++++++------------------ 4 files changed, 39 insertions(+), 23 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c2a5b554..eb91dcc0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -6,3 +6,12 @@ Code pointer: `adept/_base_.py: ergoExo#_setup_()` - The different `ADEPTModule`s are defined in subdirectories of `adept`, for example `_vlasov1d`, `_lpse2d`, etc. - `ADEPTModule`s wrap a `diffrax` differential equation solver. The RHS of the ODE (often a discretized PDE) is typically found in a file named `vector_field.py`, in the class `VectorField`. For example, the Vlasov1D RHS is defined in `adept/_vlasov1d/solvers/vector_field.py`. + +## Module Documentation + +See the [full documentation](https://ergodicio.github.io/adept/) for detailed solver guides. + +Quick links to configuration references: +- [Vlasov-1D Config](source/solvers/vlasov1d/config.md) +- [Vlasov-2D Config](source/solvers/vlasov2d/config.md) +- [LPSE-2D Config](source/solvers/lpse2d/config.md) diff --git a/docs/RUNNING_A_SIM.md b/docs/RUNNING_A_SIM.md index 8835e24b..5d4e81a4 100644 --- a/docs/RUNNING_A_SIM.md +++ b/docs/RUNNING_A_SIM.md @@ -8,6 +8,8 @@ uv run run.py --cfg path_to_my_config ## Module-Specific Configuration Reference -- [Vlasov-1D](vlasov1d.md) - 1D Vlasov-Poisson/Maxwell solver with Fokker-Planck collisions -- [Vlasov-2D](vlasov2d.md) - 2D2V Vlasov-Maxwell solver -- [LPSE-2D (Envelope-2D)](lpse2d.md) - 2D laser-plasma envelope solver for TPD/SRS +- [Vlasov-1D](source/solvers/vlasov1d/config.md) - 1D Vlasov-Poisson/Maxwell solver with Fokker-Planck collisions +- [Vlasov-2D](source/solvers/vlasov2d/config.md) - 2D2V Vlasov-Maxwell solver +- [LPSE-2D (Envelope-2D)](source/solvers/lpse2d/config.md) - 2D laser-plasma envelope solver for TPD/SRS + +See the [full documentation](https://ergodicio.github.io/adept/) for detailed guides and API reference. diff --git a/docs/requirements.txt b/docs/requirements.txt index 19fdc733..d17db314 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,3 @@ --r ../requirements-cpu.txt - # building the docs sphinx > 3.0.0 sphinx_copybutton diff --git a/docs/source/index.rst b/docs/source/index.rst index ca97e87f..b6e63deb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,8 +1,3 @@ -.. adept documentation master file, created by - sphinx-quickstart on Wed Nov 8 15:35:24 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - ADEPT ========= @@ -10,7 +5,7 @@ ADEPT :alt: ADEPT :align: right -**ADEPT** is a set of **A** utomatic **D** ifferentation **E** nabled **P** lasma **T** ransport solvers. +**ADEPT** is a set of **A** utomatic **D** ifferentiation **E** nabled **P** lasma **T** ransport solvers. Examples @@ -23,30 +18,42 @@ Documentation ------------------ .. toctree:: + :maxdepth: 2 + :caption: Getting Started + usage + +.. toctree:: + :maxdepth: 2 + :caption: Solvers + solvers + solvers/vlasov1d/overview + solvers/vlasov1d/config + solvers/vlasov2d/overview + solvers/vlasov2d/config + solvers/lpse2d/overview + solvers/lpse2d/config + solvers/vfp1d/overview + +.. toctree:: + :maxdepth: 2 + :caption: Reference + faq api - :maxdepth: 2 - :caption: Contents: + dev_guide + tests .. note:: This project is under active development. -Contributing guide +Contributing Guide ------------------------ The contributing guide is in development but for now, just make an issue / pull request and we can go from there :) Citation ------------ -[1] A. S. Joglekar and A. G. R. Thomas, “Machine learning of hidden variables in multiscale fluid simulation,” Mach. Learn.: Sci. Technol., vol. 4, no. 3, p. 035049, Sep. 2023, doi: 10.1088/2632-2153/acf81a. - - -.. Indices and tables -.. ================== - -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` +[1] A. S. Joglekar and A. G. R. Thomas, "Machine learning of hidden variables in multiscale fluid simulation," Mach. Learn.: Sci. Technol., vol. 4, no. 3, p. 035049, Sep. 2023, doi: 10.1088/2632-2153/acf81a. From 8c53a3f4d03dcddc88467d2e328fb4b13dcf9c62 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 12:08:10 -0800 Subject: [PATCH 09/11] Put config references in their own section --- docs/source/index.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index b6e63deb..c226b590 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -29,13 +29,18 @@ Documentation solvers solvers/vlasov1d/overview - solvers/vlasov1d/config solvers/vlasov2d/overview - solvers/vlasov2d/config solvers/lpse2d/overview - solvers/lpse2d/config solvers/vfp1d/overview +.. toctree:: + :maxdepth: 2 + :caption: Configuration Reference + + solvers/vlasov1d/config + solvers/vlasov2d/config + solvers/lpse2d/config + .. toctree:: :maxdepth: 2 :caption: Reference From 1743eeeb5d01b44362bdef702a9cc5d6d9074524 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 12:08:10 -0800 Subject: [PATCH 10/11] Expose raw markdown of docs under raw/ path for LLM consumers --- .github/workflows/docs.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 3929b5b4..4e2b0cf6 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -29,6 +29,15 @@ jobs: run: | uv run --with-requirements docs/requirements.txt make -C docs html + - name: Copy raw markdown sources for LLM access + run: | + mkdir -p docs/build/html/raw + cp -r docs/source/*.md docs/build/html/raw/ 2>/dev/null || true + cp -r docs/source/solvers docs/build/html/raw/ + cp -r docs/source/usage docs/build/html/raw/ + # Generate index of all markdown files for LLM discovery + cd docs/build/html/raw && find . -name "*.md" | sort > index.txt + - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: From dbb733ea6e164b75a67f27340db94139525fddb4 Mon Sep 17 00:00:00 2001 From: Jack Coughlin Date: Wed, 21 Jan 2026 12:08:10 -0800 Subject: [PATCH 11/11] Fix docs build directory in workflow --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 4e2b0cf6..273f69e2 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -41,7 +41,7 @@ jobs: - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: docs/_build/html + path: docs/build/html deploy: environment: