ORNL · pelesh · Apr 14, 2025 · Apr 12, 2025 · Apr 14, 2025 · Apr 14, 2025
diff --git a/.github/workflows/pull_request_template.md b/.github/workflows/pull_request_template.md
@@ -0,0 +1,32 @@
+## Description
+
+ _Please describe the issue that is addressed (bug, new feature,
+ documentation, enhancement, etc.). Please also include relevant motivation and
+ context. List any dependencies that are required for this change._
+
+ _Closes # (issue)_
+
+
+ ## Proposed changes
+
+ _Describe how your changes here address the issue and why the proposed changes
+ should be accepted._
+
+ ## Checklist
+
+ _Put an `x` in the boxes that apply. You can also fill these out after creating
+ the PR. If you're unsure about any of them, don't hesitate to ask. We're here
+ to help! This is simply a reminder of what we are going to look for before
+ merging your code._
+
+ - [ ] I have read the [Contributing Guide](CONTRIBUTING.md)
+ - [ ] Functionality and unit tests pass locally with my changes
+ - [ ] The code builds with flags `-Wall -Wconversion -Wextra` without any
+       compiler warnings 
+ - [ ] I have added regression tests that prove my fix is effective.
+ - [ ] I have updated the documentation (if appropriate)
+
+ ## Further comments
+
+ _If this is a relatively large or complex change, kick off the discussion by explaining
+ why you chose the solution you did and what alternatives you considered, etc..._
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Release Changelog
 
+## v0.1
+
+- Refactored code to support adding different model families.
+- Added PowerElectronics family of models.
+- Prototype for sparse system matrix assembly (for PowerElectronics only).
+- Added PhasorDynamics family of models.
+- Unit testing framework.
+- GridKit now depends on Sundials >= 7.0.
+
 ## v0.0.7
 
 - Added parser for Matpower files.

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -11,12 +11,12 @@ cmake_minimum_required(VERSION 3.12)
 project(gridkit)
 
 set(PACKAGE_NAME "GRIDKIT")
-set(PACKAGE_STRING "GRIDKIT 0.0.7")
+set(PACKAGE_STRING "GRIDKIT 0.1.0")
 set(PACKAGE_TARNAME "gridkit")
 
 set(PACKAGE_VERSION_MAJOR "0")
-set(PACKAGE_VERSION_MINOR "0")
-set(PACKAGE_VERSION_PATCH "7")
+set(PACKAGE_VERSION_MINOR "1")
+set(PACKAGE_VERSION_PATCH "0")
 
 set(PACKAGE_VERSION "${PACKAGE_VERSION_MAJOR}.${PACKAGE_VERSION_MINOR}.${PACKAGE_VERSION_PATCH}")
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,64 @@
 # Developer Guidelines
 
+## Git workflows
+
+### Keeping your local repository updated
+
+Main development branch is `develop`. The `main` branch is used for stable,
+ready-to-release code. Use `git pull` to keep `develop` branch in your local
+repo updated. If you get conflicts when pulling from upstream reset your
+local `develop` to the upstream:
+```
+git fetch
+git checkout develop
+git reset --hard origin/develop
+```
+Here `origin` is the name of the remote upstream repository in your local
+repository. If you set custom name for your remote, replace `origin` with
+that name.
+
+
+### Feature branches
+
+For each new feature feature create a new branch from `develop`. Name your
+feature branch `<developer name>/<short_feature_description>_dev. Bug fix
+branches should follow similar pattern, only ending with `_fix`. Always
+use underscores to separate different words.
+```
+git checkout -b shaked/sparse_matrix_transpose_dev
+```
+In some instances you also might want to branch off a feature branch, for
+example to fix a bug or suggest significant changes.
+
+
+### Merging your feature branch
+
+Feature branches should be merged back to the branch from where they were
+branched off (typically `develop`). All merging should be done through
+GutHub pull request. Before creating a pull request make sure:
+- All tests pass.
+- Code compiles cleanly with flags `-Wall -Wpedantic -Wconversion -Wextra`.
+- The new code follows GridKit™ style guidelines.
+- There are unit tests for the new code.
+- The new code is documented.
+- The feature branch is rebased with respect to the target branch.
+
+To rebase your feature branch, first ensure the target branch is up-to-date.
+Then use
+```
+git checkout <feature branch>
+git rebase -i <target branch>
+```
+to rebase your branch to the target branch. Follow the instructions on the
+screen. You may need to resolve rebase conflicts.
+
+Once your branch is ready, create pull request using the template provided
+in the GridKit™ repository. There has to be at least one approval before
+the pull request can be merged.
+
+
+
+
 ## Code Style
 
 ### Existing non-compliant code

diff --git a/Doxyfile b/Doxyfile
@@ -1,26 +1,3 @@
-# Doxyfile 1.8.18
-# 
-# Lawrence Livermore National Laboratory is operated by Lawrence Livermore 
-# National Security, LLC, for the U.S. Department of Energy, National 
-# Nuclear Security Administration under Contract DE-AC52-07NA27344.
-# 
-# This document was prepared as an account of work sponsored by an agency 
-# of the United States government. Neither the United States government nor 
-# Lawrence Livermore National Security, LLC, nor any of their employees 
-# makes any warranty, expressed or implied, or assumes any legal liability 
-# or responsibility for the accuracy, completeness, or usefulness of any 
-# information, apparatus, product, or process disclosed, or represents that 
-# its use would not infringe privately owned rights. Reference herein to 
-# any specific commercial product, process, or service by trade name, 
-# trademark, manufacturer, or otherwise does not necessarily constitute or 
-# imply its endorsement, recommendation, or favoring by the United States 
-# government or Lawrence Livermore National Security, LLC. The views and 
-# opinions of authors expressed herein do not necessarily state or reflect 
-# those of the United States government or Lawrence Livermore National 
-# Security, LLC, and shall not be used for advertising or product 
-# endorsement purposes. 
-#
-
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
 #

diff --git a/README.md b/README.md
@@ -1,9 +1,11 @@
 # GridKit™
 
-This is experimental code for prototyping interfaces for dynamic 
-simulations, sensitivity analysis and optimization. Target applications 
-are power grids, but the methodology and the framework could be used 
-in other areas without major modifications. 
+The objective of GridKit™ is to provide a modeling framework for power
+systems simulations and analysis that can support multiple advanced
+analysys methods, such as dynamic constrained optimization and partitioned
+numerical integrators for systems of differential and algebraic equations.
+While target applications are power grids, but the methodology and the
+framework could be used in other areas without major modifications. 
 
 ## Installation Guide
 
@@ -48,5 +50,8 @@ as functionality test and executed by running `ctest` in the build directory.
 
 ## Contributors
 
-GridKit™ is written by Slaven Peles (peless@ornl.gov) and has received contributions
-from Tamara Becejac (Avangrid), R. Cameron Rutherford (PNNL), Asher J. Mancinelli (NVIDIA), and Reid Gomillion (Virginia Tech).
+GridKit™ is written by Slaven Peles (peless@ornl.gov) and has received
+contribution from Abdourahman Barry (Virginia Tech), Tamara Becejac (Avangrid),
+Adam Birchfield (Texas A&M), Reid Gomillion (Virginia Tech), Nicholson
+Koukpaizan (ORNL), Asher J. Mancinelli (NVIDIA), Alex Novotny (Virginia Tech),
+Shaked Regev (ORNL), and R. Cameron Rutherford (PNNL).
diff --git a/cmake/FindEnzyme.cmake b/cmake/FindEnzyme.cmake
@@ -1,60 +1,4 @@
 # 
-# Copyright (c) 2017, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-# Written by Slaven Peles <peles2@llnl.gov>.
-# LLNL-CODE-718378.
-# All rights reserved.
-# 
-# This file is part of GridKit™. For details, see github.com/LLNL/GridKit 
-# Please also read the LICENSE file. 
-# 
-# Redistribution and use in source and binary forms, with or without 
-# modification, are permitted provided that the following conditions are met:
-# - Redistributions of source code must retain the above copyright notice, 
-#   this list of conditions and the disclaimer below.
-# - Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the disclaimer (as noted below) in the 
-#   documentation and/or other materials provided with the distribution.
-# - Neither the name of the LLNS/LLNL nor the names of its contributors may 
-#   be used to endorse or promote products derived from this software without 
-#   specific prior written permission.
-# 
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
-# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
-# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL
-# SECURITY, LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
-# OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISINGIN ANY 
-# WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-# THE POSSIBILITY OF SUCH DAMAGE.
-# 
-# Lawrence Livermore National Laboratory is operated by Lawrence Livermore 
-# National Security, LLC, for the U.S. Department of Energy, National 
-# Nuclear Security Administration under Contract DE-AC52-07NA27344.
-# 
-# This document was prepared as an account of work sponsored by an agency 
-# of the United States government. Neither the United States government nor 
-# Lawrence Livermore National Security, LLC, nor any of their employees 
-# makes any warranty, expressed or implied, or assumes any legal liability 
-# or responsibility for the accuracy, completeness, or usefulness of any 
-# information, apparatus, product, or process disclosed, or represents that 
-# its use would not infringe privately owned rights. Reference herein to 
-# any specific commercial product, process, or service by trade name, 
-# trademark, manufacturer, or otherwise does not necessarily constitute or 
-# imply its endorsement, recommendation, or favoring by the United States 
-# government or Lawrence Livermore National Security, LLC. The views and 
-# opinions of authors expressed herein do not necessarily state or reflect 
-# those of the United States government or Lawrence Livermore National 
-# Security, LLC, and shall not be used for advertising or product 
-# endorsement purposes. 
-# 
-
 #[[
 
 Finds Enzyme Clang plugin

diff --git a/cmake/FindIpopt.cmake b/cmake/FindIpopt.cmake
@@ -1,60 +1,4 @@
 # 
-# Copyright (c) 2017, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-# Written by Slaven Peles <peles2@llnl.gov>.
-# LLNL-CODE-718378.
-# All rights reserved.
-# 
-# This file is part of GridKit™. For details, see github.com/LLNL/GridKit 
-# Please also read the LICENSE file. 
-# 
-# Redistribution and use in source and binary forms, with or without 
-# modification, are permitted provided that the following conditions are met:
-# - Redistributions of source code must retain the above copyright notice, 
-#   this list of conditions and the disclaimer below.
-# - Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the disclaimer (as noted below) in the 
-#   documentation and/or other materials provided with the distribution.
-# - Neither the name of the LLNS/LLNL nor the names of its contributors may 
-#   be used to endorse or promote products derived from this software without 
-#   specific prior written permission.
-# 
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
-# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
-# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL
-# SECURITY, LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
-# OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISINGIN ANY 
-# WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-# THE POSSIBILITY OF SUCH DAMAGE.
-# 
-# Lawrence Livermore National Laboratory is operated by Lawrence Livermore 
-# National Security, LLC, for the U.S. Department of Energy, National 
-# Nuclear Security Administration under Contract DE-AC52-07NA27344.
-# 
-# This document was prepared as an account of work sponsored by an agency 
-# of the United States government. Neither the United States government nor 
-# Lawrence Livermore National Security, LLC, nor any of their employees 
-# makes any warranty, expressed or implied, or assumes any legal liability 
-# or responsibility for the accuracy, completeness, or usefulness of any 
-# information, apparatus, product, or process disclosed, or represents that 
-# its use would not infringe privately owned rights. Reference herein to 
-# any specific commercial product, process, or service by trade name, 
-# trademark, manufacturer, or otherwise does not necessarily constitute or 
-# imply its endorsement, recommendation, or favoring by the United States 
-# government or Lawrence Livermore National Security, LLC. The views and 
-# opinions of authors expressed herein do not necessarily state or reflect 
-# those of the United States government or Lawrence Livermore National 
-# Security, LLC, and shall not be used for advertising or product 
-# endorsement purposes. 
-# 
-
 #[[
 
 Finds Ipopt include directory and libraries and exports target `Ipopt`

diff --git a/cmake/FindSuiteSparse.cmake b/cmake/FindSuiteSparse.cmake
@@ -1,60 +1,4 @@
 # 
-# Copyright (c) 2017, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-# Written by Slaven Peles <peles2@llnl.gov>.
-# LLNL-CODE-718378.
-# All rights reserved.
-# 
-# This file is part of GridKit™. For details, see github.com/LLNL/GridKit 
-# Please also read the LICENSE file. 
-# 
-# Redistribution and use in source and binary forms, with or without 
-# modification, are permitted provided that the following conditions are met:
-# - Redistributions of source code must retain the above copyright notice, 
-#   this list of conditions and the disclaimer below.
-# - Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the disclaimer (as noted below) in the 
-#   documentation and/or other materials provided with the distribution.
-# - Neither the name of the LLNS/LLNL nor the names of its contributors may 
-#   be used to endorse or promote products derived from this software without 
-#   specific prior written permission.
-# 
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
-# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
-# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL
-# SECURITY, LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
-# OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISINGIN ANY 
-# WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-# THE POSSIBILITY OF SUCH DAMAGE.
-# 
-# Lawrence Livermore National Laboratory is operated by Lawrence Livermore 
-# National Security, LLC, for the U.S. Department of Energy, National 
-# Nuclear Security Administration under Contract DE-AC52-07NA27344.
-# 
-# This document was prepared as an account of work sponsored by an agency 
-# of the United States government. Neither the United States government nor 
-# Lawrence Livermore National Security, LLC, nor any of their employees 
-# makes any warranty, expressed or implied, or assumes any legal liability 
-# or responsibility for the accuracy, completeness, or usefulness of any 
-# information, apparatus, product, or process disclosed, or represents that 
-# its use would not infringe privately owned rights. Reference herein to 
-# any specific commercial product, process, or service by trade name, 
-# trademark, manufacturer, or otherwise does not necessarily constitute or 
-# imply its endorsement, recommendation, or favoring by the United States 
-# government or Lawrence Livermore National Security, LLC. The views and 
-# opinions of authors expressed herein do not necessarily state or reflect 
-# those of the United States government or Lawrence Livermore National 
-# Security, LLC, and shall not be used for advertising or product 
-# endorsement purposes. 
-# 
-
 #[[
 
 Finds Sutiesparse include directory and libraries and exports target `Suitesparse`