import static documentation from old gh-pages site; refresh some content

.github/workflows/deploy-docs.yml

@@ -41,6 +41,7 @@ jobs:
         run: |
           pip install mkdocs
           pip install mkdocs-literate-nav
+          pip install pymdown-extensions
 
       - name: Build User Docs
         run: mkdocs build

docs/README.md

@@ -130,7 +130,7 @@ If you want to build all the tests at once just use `make tests`.
 - `--enable-mkl[=<path>]`: use Intel MKL for FFT (and LAPACK if enabled) routines. A UNIX prefix containing the library can be specified (optional).
 - `--enable-simd=<code>`: setup Grid for the SIMD target `<code>` (default: `GEN`). A list of possible SIMD targets is detailed in a section below.
 - `--enable-gen-simd-width=<size>`: select the size (in bytes) of the generic SIMD vector type (default: 64 bytes).
-- `--enable-comms=<comm>`: Use `<comm>` for message passing (default: `none`). A list of possible SIMD targets is detailed in a section below.
+- `--enable-comms=<comm>`: Use `<comm>` for message passing (default: `none`). A list of possible communications targets is detailed in a section below.
 - `--enable-rng={sitmo|ranlux48|mt19937}`: choose the RNG (default: `sitmo `).
 - `--disable-timers`: disable system dependent high-resolution timers.
 - `--enable-chroma`: enable Chroma regression tests.

docs/api-description/coordinates.md

@@ -0,0 +1,34 @@
+---
+title : "API Documentation"
+author_profile: false
+excerpt: "Coordinates"
+header:
+  overlay_color: "#5DADE2"
+permalink: /docs/API/coordinates.html
+sidebar:
+  nav : docs
+---
+
+The Grid is define on a N-dimensional set of integer coordinates. 
+
+The maximum dimension is eight, and indexes in this space make use of the `Coordinate` class.
+The coordinate class shares a similar interface to `std::vector<int>`, but contains all data within the
+object, and has a fixed maximum length (template parameter).
+
+**Example**:
+
+```c++
+const int Nd=4;
+Coordinate point(Nd);
+
+for(int i=0;i<Nd;i++) 
+   point[i] = 1;
+
+std::cout<< point <<std::endl;
+point.resize(3);
+std::cout<< point <<std::endl;
+```
+
+This enables the coordinates to be manipulated without heap allocation or thread contention,
+and avoids introducing STL functions into GPU code, but does so at the expense of introducing
+a maximum dimensionality. This limit is easy to change (`lib/util/Coordinate.h`).

docs/api-description/grids.md

@@ -0,0 +1,92 @@
+---
+title: "Grids"
+authors:
+- Guido Cossu
+---
+
+A `Grid` object defines the geometry of a global cartesian array,
+and through inheritance provides access to
+message passing decomposition,
+the local lattice,
+and the message passing primitives.
+
+The constructor requires parameters to indicate how
+the spatial (and temporal) indices
+are decomposed across MPI tasks and SIMD lanes of the vector length.
+We use a partial vectorisation transformation,
+and must select which space-time dimensions participate in SIMD vectorisation.
+The Lattice containers are defined to have opaque internal layout,
+hiding this layout transformation.
+
+We define `GridCartesian` and `GridRedBlackCartesian`
+which both inherit from `GridBase`:
+
+```c++
+class GridCartesian        : public GridBase 
+class GridRedBlackCartesian: public GridBase 
+```
+
+The simplest Cartesian Grid constructor distributes across `MPI_COMM_WORLD`:
+
+```c++
+/////////////////////////////////////////////////////////////////////////
+// Construct from comm world
+/////////////////////////////////////////////////////////////////////////
+GridCartesian(const Coordinate &dimensions,
+  const Coordinate &simd_layout,
+  const Coordinate &processor_grid);
+```
+
+A second constructor will create a child communicator from a previously declared Grid.
+This allows to subdivide the processor grid,
+and also to define lattices of differing dimensionalities and sizes,
+useful for both Chiral fermions, lower dimensional operations, and multigrid:
+
+```c++
+/////////////////////////////////////////////////////////////////////////
+// Constructor takes a parent grid and possibly subdivides communicator.
+/////////////////////////////////////////////////////////////////////////
+GridCartesian(const Coordinate &dimensions,
+        const Coordinate &simd_layout,
+        const Coordinate &processor_grid,
+        const GridCartesian &parent,int &split_rank);
+```
+
+The Grid object provides much `internal` functionality
+to map a lattice site to a node and lexicographic index.
+These are not needed by code interfacing to the data parallel layer.
+
+**Example** (`tests/solver/Test_split_grid.cc`):
+
+```c++
+  const int Ls=8;
+
+  ////////////////////////////////////////////
+  // Grids distributed across full machine
+  // pick up default command line args
+  ////////////////////////////////////////////
+  Grid_init(&argc,&argv);
+
+  Coordinate latt_size   = GridDefaultLatt();
+  Coordinate simd_layout = GridDefaultSimd(Nd,vComplex::Nsimd());
+  Coordinate mpi_layout  = GridDefaultMpi();
+
+  GridCartesian * UGrid = SpaceTimeGrid::makeFourDimGrid(GridDefaultLatt(), 
+                            GridDefaultSimd(Nd,vComplex::Nsimd()),GridDefaultMpi());
+  GridCartesian         * FGrid   = SpaceTimeGrid::makeFiveDimGrid(Ls,UGrid);
+  GridRedBlackCartesian * rbGrid  = SpaceTimeGrid::makeFourDimRedBlackGrid(UGrid);
+  GridRedBlackCartesian * FrbGrid = SpaceTimeGrid::makeFiveDimRedBlackGrid(Ls,UGrid);
+
+  /////////////////////////////////////////////
+  // Split into N copies of 1^4 mpi communicators
+  /////////////////////////////////////////////
+  Coordinate mpi_split (mpi_layout.size(),1);
+  GridCartesian * SGrid = new GridCartesian(GridDefaultLatt(),
+                                GridDefaultSimd(Nd,vComplex::Nsimd()),
+                                mpi_split,
+                                *UGrid); 
+
+  GridCartesian         * SFGrid   = SpaceTimeGrid::makeFiveDimGrid(Ls,SGrid);
+  GridRedBlackCartesian * SrbGrid  = SpaceTimeGrid::makeFourDimRedBlackGrid(SGrid);
+  GridRedBlackCartesian * SFrbGrid = SpaceTimeGrid::makeFiveDimRedBlackGrid(Ls,SGrid);
+```

docs/api-description/introduction.md

@@ -0,0 +1,46 @@
+---
+title: "Data parallel API"
+authors:
+- Guido Cossu
+- Ed Bennett
+---
+
+!!! warning
+
+    These documents have not been updated for changes in Grid
+    since they were written in 2018.
+    For many aspects of Grid,
+    more up-to-date information is available through
+    the [Doxygen][doxygen] documentation,
+    which will be the focus of updates going forward.
+    However,
+    until those updates progress,
+    the documentation here gives a not-entirely inaccurate
+    high-level overview of Grid's structure and philosophy.
+
+Data parallel array indices are divided into two types. 
+
+* Internal indices, such as complex, colour, spin degrees of freedom 
+* spatial (space-time) indices.
+
+The ranges of all internal degrees are determined by template parameters, 
+and known at compile time.
+The ranges of spatial indices are dynamic,
+run time values
+and the Cartesian structure information
+is contained and accessed via `Grid` objects.
+
+Grid objects are the controlling entity for
+the decomposition of a distributed `Lattice` array
+across MPI tasks, nodes, SIMD lanes, accelerators.
+Threaded loops are used as appropriate on host code.
+
+Data parallel operations
+can only be performed between Lattice objects constructed from the same Grid pointer.
+These are called `conformable` operations.
+
+We will focus initially on the internal indices
+as these are the building blocks assembled in Lattice container classes.
+Every Lattice container class constructor requires a Grid object pointer. 
+
+[doxygen]: <../../dev>