From 3e947eef0f008e07cb43f4b97f520073ac97948c Mon Sep 17 00:00:00 2001
From: Archis Joglekar <joglekara@users.noreply.github.com>
Date: Wed, 31 Jul 2024 21:26:40 -0700
Subject: [PATCH] Vlasov1D1V documentation (#59)

* Vlasov1D1V docs update

* ergoExo docs
---
 docs/source/api.rst                | 25 +++++++++++++++++++++++++
 docs/source/index.rst              |  1 +
 docs/source/solvers.rst            | 10 ++++++++++
 docs/source/solvers/vlasov1d1v.rst | 27 +++++++++++++++++++++++++++
 4 files changed, 63 insertions(+)
 create mode 100644 docs/source/solvers.rst
 create mode 100644 docs/source/solvers/vlasov1d1v.rst

diff --git a/docs/source/api.rst b/docs/source/api.rst
index 27cd9b6..3f5ae71 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -6,6 +6,31 @@ There are two primary high level classes.
 1. `ergoExo` houses the solver and handles the mlflow logging and experiment management
 2. `ADEPTModule` is base class for the solver
 
+If you wanted to create your own differentiable program that uses the ADEPT solvers, you could do
+
+.. code-block:: python
+
+   from adept import ergoExo
+
+   exo = ergoExo()
+   modules = exo.setup(cfg)
+
+and 
+
+.. code-block:: python
+
+   sol, ppo, run_id = exo(modules)
+
+or 
+
+.. code-block:: python
+
+   sol, ppo, run_id = exo.val_and_grad(modules)
+
+This is analogous to `torch.nn.Module` and `eqx.Module` the `Module` workflows in general.
+
+You can see what each of those calls does in API documentation below.
+
 .. toctree::
    ergoExo
    ADEPTModule
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6d283a9..f31c7b0 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -30,6 +30,7 @@ Documentation
 
 .. toctree::
    usage
+   solvers
    faq
    api
    :maxdepth: 1
diff --git a/docs/source/solvers.rst b/docs/source/solvers.rst
new file mode 100644
index 0000000..af7b485
--- /dev/null
+++ b/docs/source/solvers.rst
@@ -0,0 +1,10 @@
+Available solvers
+==================
+
+The solvers that we have implemented so far are
+
+
+.. toctree::
+   solvers/vlasov1d1v
+   :maxdepth: 1
+   :caption: Implemented solvers:
diff --git a/docs/source/solvers/vlasov1d1v.rst b/docs/source/solvers/vlasov1d1v.rst
new file mode 100644
index 0000000..67b1a78
--- /dev/null
+++ b/docs/source/solvers/vlasov1d1v.rst
@@ -0,0 +1,27 @@
+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.
+
+
+Solver Options
+================
+This is where we should have a list of the different solvers that can be chosen including the collision operator. #TODO
+
+Configuration parameters
+========================
+This is where there should be a line by line explanation of everything in a config file... #TODO
\ No newline at end of file