Governor Documentation and Model

.devcontainer/Dockerfile

@@ -0,0 +1,31 @@
+FROM ubuntu:24.04
+
+RUN apt update -y && apt install -y --no-install-recommends\
+	gcc \
+	g++ \
+	make \
+	cmake \
+	ninja-build \
+	git \
+	ca-certificates \
+	libopenblas-dev \
+	&& apt clean && rm -rf /var/lib/apt/lists/*
+
+# Install SuiteSparse for klu
+RUN git clone --single-branch --depth 1 --branch v7.10.2 https://github.com/DrTimothyAldenDavis/SuiteSparse.git /tmp/suitesparse && \
+	cd /tmp/suitesparse && \
+	mkdir -p build && cd build && \
+	cmake -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+		-DSUITESPARSE_ENABLE_PROJECTS="klu" .. && \
+	ninja install && \
+	rm -rf /tmp/suitesparse
+
+# Install sundials using klu from previous step
+RUN git clone --single-branch --branch develop https://github.com/LLNL/sundials.git /tmp/sundials && \
+	cd /tmp/sundials && \
+	git checkout 07d21c2c5ae33211a9a2fafd8eac56de5582dce0 && \
+	mkdir -p build && cd build && \
+	cmake -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+		-DENABLE_KLU=ON .. && \
+	ninja install && \
+	rm -rf /tmp/sundials

.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-vscode.cpptools"
+			]
+		}
+	}
+}

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[{CMakeLists.txt,*.{cpp,hpp,tpp,sh,h,cu,hip,cmake}}]
+indent_style = space
+indent_size = 2
+
+[*.{json,m}]
+indent_style = space
+indent_size = 4

.github/workflows/spack_default_build.yaml

@@ -1,13 +1,13 @@
 # https://spack.readthedocs.io/en/latest/binary_caches.html#spack-build-cache-for-github-actions
-name: Spack Ubunutu x86_64 Buildcache
+name: CPU tests (Ubunutu x86_64)
 
 env:
   SPACK_COLOR: always
   REGISTRY: ghcr.io/ornl
   # Our repo name contains upper case characters, so we can't use ${{ github.repository }}
   IMAGE_NAME: gridkit
   USERNAME: gridkit-bot
-  BASE_VERSION: ubuntu-24.04-fortran-v0.2.11
+  BASE_VERSION: ubuntu-24.04-fortran-v0.2.12
 
 # Until we remove the need to clone submodules to build, this should on be in PRs
 on: [pull_request]
@@ -92,7 +92,7 @@ jobs:
     permissions:
       packages: write
       contents: read
-    timeout-minutes: 30
+    timeout-minutes: 60
 
     strategy:
       matrix:
@@ -101,6 +101,9 @@ jobs:
         spack_spec:
           - gridkit@develop +enzyme
             ^enzyme@0.0.173
+            ^sundials@develop
+          - gridkit@develop ~enzyme
+            ^sundials@develop
 
     steps:
       - name: Add LLVM
@@ -127,13 +130,14 @@ jobs:
             specs:
             - ${{ matrix.spack_spec }} target=x86_64_v2
             concretizer:
+              unify: true
               reuse: dependencies
             config:
               install_tree:
                 root: /opt/spack
                 padded_length: 128
             mirrors:
-              local-buildcache: oci://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+              local-buildcache: oci://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}/${{ env.BASE_VERSION }}
               spack: https://binaries.spack.io/v0.23.1
             packages:
               llvm:

.pre-commit-config.yaml

@@ -3,6 +3,7 @@ repos:
     rev: v19.1.7
     hooks:
     - id: clang-format
+      types_or: [c++, c, cuda]
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:

CMakeLists.txt

@@ -20,11 +20,14 @@ set(PACKAGE_VERSION_PATCH "0")
 
 set(PACKAGE_VERSION "${PACKAGE_VERSION_MAJOR}.${PACKAGE_VERSION_MINOR}.${PACKAGE_VERSION_PATCH}")
 
-# TODO: Probably beter to set a debug interface target
-# set(CMAKE_CXX_FLAGS_DEBUG "-Wall -O0 -g -DDEBUG")
-
 set(CMAKE_CXX_STANDARD 17)
 
+if (MSVC)
+  set(CMAKE_CXX_FLAGS "/Wall")
+else()
+  set(CMAKE_CXX_FLAGS "-Wall -Wextra -Wconversion -Wpedantic")
+endif()
+
 # Ipopt support is disabled by default
 option(GRIDKIT_ENABLE_IPOPT "Enable Ipopt support" OFF)
 
@@ -37,6 +40,22 @@ option(GRIDKIT_ENABLE_SUNDIALS_SPARSE "Enable SUNDIALS sparse linear solvers" ON
 # Enzyme support is disabled by default
 option(GRIDKIT_ENABLE_ENZYME "Enable automatic differentiation with Enzyme" OFF)
 
+# Enable the address sanitizer
+option(GRIDKIT_ENABLE_ASAN "Enable the address sanitizer" OFF)
+
+if(GRIDKIT_ENABLE_ASAN)
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=address -fno-omit-frame-pointer")
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fsanitize=address")
+endif()
+
+# Enable the undefined behavior sanitizer
+option(GRIDKIT_ENABLE_UBSAN "Enable the undefined behavior sanitizer" OFF)
+
+if(GRIDKIT_ENABLE_UBSAN)
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=undefined -fno-omit-frame-pointer")
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fsanitize=undefined")
+endif()
+
 set(CMAKE_MACOSX_RPATH 1)
 set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS 1)
 
@@ -73,7 +92,7 @@ if(GRIDKIT_ENABLE_IPOPT)
   enable_language(Fortran) # Needed for linking to HSL
 endif()
 if(GRIDKIT_ENABLE_SUNDIALS)
-  find_package(SUNDIALS 7.0.0 REQUIRED CONFIG 
+  find_package(SUNDIALS 7.0.0 REQUIRED CONFIG
                PATHS ${SUNDIALS_DIR}
                      ${SUNDIALS_DIR}/lib/cmake/sundials)
   message(STATUS "SUNDIALS configuration found: ${SUNDIALS_CONFIG}")
@@ -84,6 +103,8 @@ endif()
 
 if(${GRIDKIT_ENABLE_ENZYME})
   include(FindEnzyme)
+  # todo Add a centralized configuration file
+  add_definitions(-DGRIDKIT_ENABLE_ENZYME)
 endif()
 
 # Macro that adds libraries
@@ -97,7 +118,7 @@ add_subdirectory(src)
 enable_testing()
 add_subdirectory(examples)
 add_subdirectory(tests)
-  
+
 export(EXPORT gridkit-targets FILE ${CMAKE_CURRENT_BINARY_DIR}/GridKitTargets.cmake)
 
 # Configuring exporting cmake config

CONTRIBUTING.md

@@ -57,6 +57,64 @@ in the GridKit™ repository. There has to be at least one approval before
 the pull request can be merged.
 
 
+## Documenting Code
+
+### Doxygen
+All comments in the code should follow [Doxygen](https://www.doxygen.nl/manual/index.html)
+markup. For uniformity, we recommend C-style Doxygen comments starting with
+two `*`.
+
+### Documenting functions
+Functions should be documented in source files. The rationale is to have
+the documentation near the implementation, so that is handy to a developer and
+can be updated quickly when the function modified.
+
+### Minimal function documentation
+Function documentation should include specification of function parameters,
+template parameters (if any), return value, preconditions, postconditions,
+and invariants.
+
+```c++
+/**
+ * @brief <BRIEF DESCRIPTION>
+ *
+ * @param <NAME> <DESCRIPTION>
+ * @tparam <NAME> <DESCRIPTION>
+ * @return <DESCRIPTION OF RETURN VALUE>
+ *
+ * @pre <PRECONDITION>
+ * @post <POSTCONDITION>
+ *
+ * LONGER DESCRIPTION, RUNTIME, EXAMPLES, ETC 
+ */
+```
+
+* `@brief` marks the text that will be displayed in summaries and index lists.
+Typically you would put here a few words description of your function.
+* `@param` describes a function parameter and takes an optional direction:
+`@param[in]` means the parameter's value is only read and not modified within
+the function, `@param[out]` means the parameter is not read and is only
+modified, and `@param[in,out]` means the parameter is both read and modified.
+* `@pre` and `@post` define the pre- and postconditions, which should be
+precise but brief. When in doubt, attempt rigorous conditions but keep in mind
+that some concepts such as "validity" may be difficult or impossible to define
+precisely. Specifications are primarily for human consumption.
+* `@param`, `@pre`, and `@post` sections should be repeated as many time as
+required.
+
+
+### Doxygen and Markdown
+
+Doxygen supports Markdown markup and it should be used to make documentation
+more clear. For example, 
+```c++
+ * @return The size of `a`
+```
+is clearer than 
+```c++
+ * @return The size of a
+```
+when read in plain text and in formatted documentation.
 
 
 ## Code Style
@@ -126,6 +184,24 @@ double another_member;   // No, there is no trailing underscore to distinguish i
 double memberVariable_;  // No, using lowercase camel instead of C-style name format
 ```
 
+#### Ecxeption
+
+Public member variables that are accessed directly do not need trailing
+underscores. For example, consider this code:
+```c++
+struct ModelData
+{
+  int id;
+  double value;
+};
+
+ModelData data;
+data.id = 1;
+data.value = 2.0;
+```
+Member variables of struct `data` are accessed diorectly outside the struct
+and do not need to be denoted with trailing underscores `_`.
+
 ### Function names
 
 Use lowercase camel format for function names.
@@ -399,3 +475,7 @@ class Matrix   // No, class is outside GridKit namespace
 {
   // matrix code
 };
+```
+
+## Development Container
+A development container is available for all developers using VS Code to develop. This will automatically install all pre-requisite software you need to develop in GridKit. Any developer who wishes to use this setup can follow [this tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) and simply use the option "Reopen Folder in Container" rather than "New Dev Container...", which will automatically build the included container.

README.md

@@ -18,7 +18,7 @@ Before installing GridKit™ make sure you have all needed dependencies.
 ### Dependencies
 You should have all of the following installed before installing GridKit™
 - A version of
-    - [SUNDIALS](https://github.com/LLNL/sundials) >= 7.0.0
+    - [SUNDIALS](https://github.com/LLNL/sundials) `develop` branch at commit >= [`07d21c2`](https://github.com/LLNL/sundials/commit/07d21c2c5ae33211a9a2fafd8eac56de5582dce0)
     - [Suitesparse](https://github.com/DrTimothyAldenDavis/SuiteSparse) >= 5.x (optional)
         - If using Suitesparse, SUNDIALS must also be built with [KLU support](https://sundials.readthedocs.io/en/latest/sundials/Install_link.html#cmakeoption-ENABLE_KLU)
     - [Ipopt](https://github.com/coin-or/Ipopt) >= 3.x (optional)