From 7f3bd0037b7568231603c309b5aa3e6af3e1cad9 Mon Sep 17 00:00:00 2001
From: Matthew Carbone <x94carbone@gmail.com>
Date: Sun, 17 Dec 2023 21:21:57 -0500
Subject: [PATCH] Add beginnings of docs

---
 README.md           |  4 ++++
 docs/observables.md | 15 +++++++++++++++
 2 files changed, 19 insertions(+)
 create mode 100644 docs/observables.md

diff --git a/README.md b/README.md
index ec0f218..546ef67 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,10 @@ _If you use this code, please consider citing our [work](https://doi.org/10.1103
 
 ⚡ [MPI load-balancer](https://github.com/matthewcarbone/hdspin/blob/master/src/main_utils.cpp), allowing for massively parallel simulations on high-performance computing systems. The rare time-consuming job no longer holds up other simulations.
 
+# ⭐️ Documentation
+
+TK
+
 # 📕 Installation instructions
 
 hdspin requires [MPI](http://www.mpi-forum.org), and is tested using [MPICH](https://www.mpich.org) and [Open MPI](https://www.open-mpi.org) on both Ubuntu latest and MacOS. Other than that, every external dependency is self-contained explicitly under the terms of their licences. Installing hdspin should be straightforward using CMake:
diff --git a/docs/observables.md b/docs/observables.md
new file mode 100644
index 0000000..4a56af6
--- /dev/null
+++ b/docs/observables.md
@@ -0,0 +1,15 @@
+# Observables
+
+We outline the various observables that hdspin calculates.
+
+- Statistics are not saved at every timestep. As it is possible to have many millions of timesteps, this is not tractable from a storage standpoint. Grids are generally linear in log-space, and observables are saved only at those timesteps.
+- Most observables have a variety of statistics saved, including the mean, standard deviation, standard error, and median (at every timestep on the grid).  
+- All averaged statistics can be found in the `results.json` file saved at the end of the simulation.
+
+## Average energy
+
+Consider the energy of tracer $i$ at simulation clock time $t$ is $E_{i}(t).$ The average energy over $N$ tracers is simply given by
+
+$$ E(t) = \frac{1}{N} \sum_{i=1}^N E_i(t).$$
+
+Results for the energy can be accessed via `results["energy"]`.