Jenkins for CI

.agents/skills/compiling/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: compiling
+description: How to compile Gkeyll libraries, executables, and specific unit or regression test targets on CPU or CUDA.
+---
+
+# Instructions
+
+Use this skill whenever you need to compile
+* Any of the Gkeyll libraries.
+* A C unit or regression test.
+* A C input file.
+
+# Compiling in Gkeyll
+
+We assume the dependencies have already been installed (e.g. via a machines/mkdeps
+file) and configured (e.g. via a machines/configure file).
+
+Operate relative to the repository root (`git rev-parse --show-toplevel`).
+Dependencies are typically already installed in the sibling `gkylsoft/`
+directory. Check the existing configuration before building. If configuration
+is missing or needs changing, consult `machines/configure.<machine>.sh` for
+required modules and library paths, or use `./configure` with the intended
+installation prefix and solver.
+
+## Compiling the Gkeyll library
+
+We compile using a Makefile. The `make` command allows you to specify the number
+of cores to use via `-j`. We will use no more than half the available processors for parallel builds.
+So before invoking `make`, set the `NPROC` environment variable on a Mac using
+```
+export NPROC=$(sysctl -n hw.physicalcpu)
+NPROC=$((NPROC > 1 ? NPROC / 2 : 1))
+```
+or on Linux using
+
+```sh
+NPROC=$(nproc)
+NPROC=$((NPROC > 1 ? NPROC / 2 : 1))
+```
+
+Then, you can build the Gkeyll library with
+
+```sh
+make -j"$NPROC" install
+```
+
+## Compiling a C unit or regression test
+
+Unit tests are located in the `unit/` directory of each solver
+(core/moments/vlasov/gyrokinetic/pkpm), while C regression tests are located in `creg/` folders and
+have names beginning with `rt_`.
+
+Compile a specific test by giving make its executable target:
+
+```sh
+make -j"$NPROC" build/core/unit/ctest_array
+make -j"$NPROC" build/gyrokinetic/creg/rt_gk_sheath_2x2v_p1
+```
+
+CPU targets are located in `build/`, and  GPU targets are in `cuda-build/`.
+Match test targets to the configured build directory.
+
+For executing the resulting tests, see
+[testing_and_verification](../testing_and_verification/SKILL.md).
+
+### Compiling all or groups of C unit tests
+
+The Makefile supports compiling groups of unit tests all at once. For example, to compile all the
+unit tests at once run
+
+```sh
+make -j"$NPROC" unit
+```
+
+Alternatively, you can compile all the unit tests for a specific solver. For example, to compute all
+the unit tests for the gyrokinetic solver use
+
+```sh
+make -j"$NPROC" unit-run
+```
+
+## Compiling C input files
+
+Input files written in C work just like C regression tests. They can be compiled similarly if they
+are located in the `creg/` folder. For example, if `my_sim.c` is a gyrokinetic input file, and located
+in `gyrokinetic/creg/`, it can be compiled with
+
+```sh
+make -j"$NPROC" build/gyrokinetic/creg/my_sim
+```
+
+If the input file is outside of the repository, one needs to use the shared makefile in
+`<path_to_gkylsoft>/gkylsoft/gkeyll/share/`. For example, if `my_other_sim.c` is an input file in `$HOME/new_sim/`,
+compile it with: 
+
+```sh
+cd ~
+cp <path_to_gkylsoft>/gkylsoft/gkeyll/share/Makefile ./
+make
+```

.agents/skills/directory_structure/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: directory_structure
+description: Explanation of the Gkeyll directories.
+---
+
+# Instructions
+
+* Use when exploring the repository, trying to find something, or deciding where new code belongs.
+* Operate relative to the repository root (`git rev-parse --show-toplevel`).
+
+# Gkeyll file structure
+
+Gkeyll has four PDE solvers: 
+* Moments or fluid solver.
+* Vlasov solver.
+* Gyrokinetic solver.
+* PKPM solver.
+
+Correspondingly, these solvers are organized into four separate folders, and they
+share some common functionality in a fifth folder. Gkeyll is mostly organized in:
+* core/: functionality common to all solvers.
+* moments/: files for the moments solver.
+* vlasov/: files for the Vlasov solver.
+* gyrokinetic/: files for the gyrokinetic solver.
+* pkpm/: files for the PKPM solver.
+
+Note that the four solvers are not independent. They have the following
+dependencies:
+* moments depends on core.
+* vlasov depends on moments.
+* gyrokinetic depends on vlasov.
+* pkpm depends on gyrokinetic.
+
+Keep lower layers independent of higher layers.
+
+Each of the solvers' folders have the sub-folders:
+* ker/: C kernels generated with Maxima stored in the gkylcas repository. Do
+  not hand-edit generated kernels; modify their source templates instead.
+* zero/: C and CUDA functions or modules (sometimes we call them updaters),
+  some of which call kernels in ker/.
+* data/: data needed for some simulations.
+* unit/: unit tests of specific components in zero/.
+* apps/: apps are called by input files or regression tests, and they organize
+  solver workflow or simulations and call modules in zero/. Communication
+  happens in the app level.
+* creg/: C regression tests or short simulations to ensure solvers work (these
+  are also examples of C input files).
+* luareg/: Lua regression tests or short simulations to ensure solvers work
+  (these are also examples of Lua input files).
+
+## Library dependencies
+
+The Gkeyll source code in gkeyll/ depends on other libraries installed in gkylsoft/.
+Most of the time you shouldn't need to read files in gkylsoft/ unless prompted.
+
+## CPU - GPU organization
+
+Gkeyll runs on both CPUs and GPUs, the latter using CUDA.
+- CPU-only implementations live in .c files.
+- C files call host-side wrappers of CUDA kernels, both of which live in _cu.cu
+  files.
+
+## Search hierarchy
+
+Rather than looking into the entire codebase without prior knowledge, look into
+folders in the following order:
+- Look into a folder (ending in /) the user referenced.
+- If the user referenced a specific solver (e.g. gyrokinetic), look into its
+  folder.
+- Look into folders for solvers that the specified solver depends on, following
+  the dependency chain up through core/.

.agents/skills/gyrokinetic_details/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gyrokinetic_details
+description: Details specific to the gyrokinetic solver.
+---
+
+# Instructions
+
+* Use when working on the gyrokinetic/ code, or with an input file that uses
+  the gyrokinetic solver.
+
+# Gyrokinetics
+
+## MPI decomposition
+
+Gyrokinetic regression tests parallelize along the last configuration-space
+dimension. Choose the partition flag by dimensionality:
+
+| Dimensionality | Flag for N partitions |
+|---|---|
+| 1x2v | `-c N` |
+| 2x2v | `-d N` |
+| 3x2v | `-e N` |
+
+For example, run the compiled 2x2v sheath regression on four MPI ranks:
+
+```sh
+<path_to_gkylsoft>/gkylsoft/openmpi/bin/mpirun -np 4 ./build/gyrokinetic/creg/rt_gk_sheath_2x2v_p1 -M -d 4
+```
+
+Use the MPI installation matching the build. `-M` enables MPI in the
+regression executable; `-d 4` partitions its second configuration dimension.
+Add `-s1` for a one-step smoke test.
+
+See [compiling](../compiling/SKILL.md) when a build is needed,
+and [testing_and_verification](../testing_and_verification/SKILL.md) for general test
+execution and memory checks.

.agents/skills/naming_conventions/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: naming_conventions
+description: Determine the correct name for files, functions, modules and variables.
+---
+
+# Instructions
+
+* Apply these naming conventions when creating, editing, or reviewing C, CUDA, and Lua code.
+
+# Naming conventions
+
+### Files.
+
+- Public header files have names starting with gkyl_ and ending in .h.
+- Private header files have names starting with gkyl_ and ending in _priv.h.
+- CUDA files have names ending in _cu.cu. 
+- luareg/ folders have Lua input files whose names end with .lua. The Lua
+  wrappers are in the apps/ folders and have names ending in _lw.c
+
+### Functions
+
+- Public functions (defined in public header files) should have a name that starts
+  with gkyl_.
+- Public functions in files in zero/ folders should have a name that starts
+  with the name of the file that contains it.
+- Private functions (defined in private header files) or static (and not defined
+  in private headers) in files in zero/ folders should have a name that starts
+  with an abbreviated version of the name of the file that contains it.
+
+### Variables
+
+- Do not use single letter names for variables whose scope spans more than 15 lines.
+

.agents/skills/software_design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: software_design
+description: Some design practices in Gkeyll code to consider when implementing new modules (apps, updaters) or modifying existing ones.
+---
+
+# Instructions
+
+* Load this skill whenever new modules or updaters in zero/ or apps/ folders
+  are to be created, or when existing ones will be edited.
+
+## Software design elements
+
+### Module structure
+
+Most modules in zero/ or apps/ consist of 3 public functions:
+1. A creation function, typically called gkyl_<module>_new or gkyl_<module>_init.
+2. An execution function, often called gkyl_<module>_advance or gkyl_<module>_apply.
+3. A deletion function, typically called gkyl_<module>_release.
+
+There may also be some additional auxiliary private or public functions.
+
+### Module best practices
+
+- All dynamic (heap) allocations should happen in the initialization function,
+  and freed in the release function, using the appropriate gkyl_ allocation/deallocation functions when possible.
+- Don't place logic branching (e.g. if-statements) that depend on a
+  time-independent choice or parameter inside the methods called in the time loop of a simulation (e.g. _advance). Instead, use function pointers to set the appropriate method during the initialization of the module, and call that method inside the time loop.
+
+### Other principles to follow
+
+- Consider extensibility, maintainability, simplicity and how modular design.
+- Avoid code duplication whenever possible (e.g. write functions called
+  multiple times) and without breaking layering.
+- Write shorter code and refactor into a sub-module whenever possible.