SUNDIALS Developers Guide¶

Introduction¶

The SUite of Nonlinear and DIfferential/ALgebraic equation Solvers (SUNDIALS) consists of the time integration packages CVODE, IDA, and ARKODE, the sensitivity analysis enabled variants CVODES and IDAS, and the nonlinear solver package KINSOL.

History¶

SUNDIALS originated in 1993 as a rewrite in C of two general purpose Fortran solvers for Ordinary Differential Equations, VODE and VODPK. These packages had evolved from some of the first and most heavily used ODE integrator packages ever developed, first available through the NETLIB FTP site as part of ODEPACK (which had more than 250,000 downloads). Based on linear multistep methods for both non-stiff and stiff systems, these solvers used adaptive time-stepping and variable-order schemes to deliver solutions whose error within each time step was bounded by user-supplied tolerances. The VODE line of codes represented a breakthrough in general purpose ODE integrators in that they used variable-coefficient multistep methods instead of fixed-step-interpolated methods. The variable coefficient form allowed for efficient solvers tuned through integrator heuristics. The goal of the 1993 rewrite was a version of these heavily used solvers that could be easily extended from serial to distributed memory parallel computers. The resulting serial code, called CVODE, was followed by a parallel version, called PVODE. The ease of making this conversion was achieved by the use of two sets of routines for basic vector operations, one serial and one parallel (based on MPI).

The success of the rewrite prompted a similar rewrite of a nonlinear algebraic systems solver, NKSOL, which was the first Newton-Krylov-based nonlinear software package, into the KINSOL package. (CNKSOL was voted out as a name due to a desire of LLNL management for a pronounceable package name, hence KINSOL, for Krylov Inexact Newton SOLver.) Further development of the common infrastructure led to a C rewrite of a pair of differential-algebraic system solvers, DASSL and DASPK, resulting in the IDA package. The original name for this group of three codes was “The PVODE Trio.” With careful encapsulation of data vectors, the codes were engineered so that the core integrator and nonlinear solvers were the same whether run in serial or parallel. With this advance, the “P” was replaced with “C” in the CVODE name making the PVODE Trio name obsolete. The group of packages were then given the acronym SUNDIALS, for SUite of Nonlinear DIfferential and ALgebraic equation Solvers, and first released under that name in 2002.

Extensions to the time integrators to handle forward and adjoint sensitivity problems, called CVODES and IDAS, were added later. In 2015 a new ODE integration package, ARKode, was added to SUNDIALS. ARKode includes multistage methods which are better suited to time evolution systems posed within spatially adaptive codes than the multistep methods in CVODE. The six packages in SUNDIALS all share a collection of vector operation modules, which originally included serial and MPI-parallel versions. In 2015, versions supporting threaded environments were added, and in 2017 GPU support through CUDA and RAJA was added. Recent extensions to SUNDIALS have included wrappers for PETSc and hypre vectors. Richer interoperability layers with those and other DOE solver packages are planned through the Exascale Computing Project.

A timeline of SUNDIALS development:

1982 - First release of ODEPACK

1986 – 1991 - Development of VODE and VODPK

1993 - Initial rewrite of VODE/VODPK into CVODE

1994 - CVODE first released

1995 - Initial version of PVODE written

1998 - PVODE first released

1998 - KINSOL first released

1999 - IDA first released

2002 - First release of SUNDIALS under a BSD license

2004 - CVODES first released

2009 - IDAS first released

2015 - ARKode first released as part of SUNDIALS

2016 - Changed procedures to allow for unregistered downloads

2017 - Created GitHub mirror of released software for download

Getting Started¶

SUNDIALS uses Git for distributed version control. If you have not setup Git on your system, see the Git Setup section for details on configuring Git and cloning the SUNDIALS repository. A list of helpful commands can be found in the Git Cheat Sheet. The typical evelopment workflow is described in the Workflow section.

Git Setup¶

SSH Keys¶

One-time setup of ssh keys to avoid needing a password with each repository transaction.

Create your ssh key using the ssh-keygen utility:
1. Skip this first command if you already have a public/private ssh key (i.e., you already have an id_rsa.pub file in your ~/.ssh directory):
```
$ ssh-keygen -t rsa
```
2. Make sure that your ssh directory (~/.ssh) is readable only by you.
```
$ chmod -R go-rwx ~/.ssh
```
Install the key in Bitbucket:
1. Log in to http://mybitbucket.llnl.gov
2. Click on the profile drop down in the far top right of the window and select “Manage Account”
3. Click on the “SSH keys” link on the left of the screen and then “Add key”
4. Paste your key into the text box. The text of the key is the contents of the file ~/.ssh/id_rsa.pub

Git Configuration¶

Global Git configuration information is stored in ~/.gitconfig and can be set with the git config --global command or by editing the .gitconfig file manually. More information is available in the git config documentation. Note in the comments in the .gitconfig file begin with #.

Tell Git who you are:

$ git config --global user.name "Your Name"
$ git config --global user.email "yourname@example.com"

— OR —

[user]
    name = Your Name             # name recorded in commits
    email = yourname@example.com # email recorded in commits

Tell Git to only push changes on your current branch and only if the upstream branch has the same name i.e., don’t default to push changes to all branches or branches with a different name. Note the behavior is the default beginning with Git v2.0.
```
$ git config --global push.default simple
```
— OR —
```
[push]
    default = "simple" # push current branch to upstream branch with same name
```

Tell Git which editor you want to use by default (e.g., Emacs):

$ git config --global core.editor "emacs"

— OR —

[core]
     editor = emacs # default editor

Enable color output in Git

$ git config --global color.ui "true"

— OR —

[color]
     ui = true # enable color output

The following settings enable using a graphical diff tool to resolve conflicts during a merge or when viewing diffs between files. These settings are optional but may be useful. The settings below are given for the meld diff tool. Similar settings can be used with emerge, gvimdiff, kdiff3, vimdiff, and tortoisemerge.

To add a merge tool (invoked by git mergetool), add the following to the ~/.gitconfig file:

[mergetool "meld"]
    # command to invoke the merge tool for newer versions of
    # meld which use the '--output' option
    cmd = meld "$LOCAL" "$MERGED" "$REMOTE" --output "$MERGED"

To add a diff tool (invoked by git difftool), add the following to the ~/.gitconfig file:

[diff]
    # which diff tool Git should use
    tool = meld
[difftool]
    # do not prompt before each invocation of the diff tool
    prompt = false
[difftool "meld"]
    # command to invoke the diff tool
    cmd = meld "$LOCAL" "$REMOTE"

Additionally, Git provides helpful scripts to enable auto-completion of Git commands and to display the current status in the command line prompt for various shells. The scripts git-completion.* and git-prompt.sh can be obtained from the contrib/completion directory in the Git source repository on GitHub.

For example with Bash, auto-completion can be enabled by adding

source <some-path>/git-completion.bash

to your .bashrc file. Similarly displaying the Git command line prompt information can be enabled by adding

export GIT_PS1_SHOWDIRTYSTATE="true"       # unstaged *, staged +
export GIT_PS1_SHOWSTASHSTATE="true"       # stashed $
export GIT_PS1_SHOWUNTRACKEDFILES="true"   # untracked %
export GIT_PS1_SHOWUPSTREAM="auto verbose" # ahead +, behind -, diverged +-, same =
export GIT_PS1_SHOWCOLORHINTS="true"
source <some-path>/git-prompt.sh

export PROMPT_COMMAND='__git_ps1 "[$(date +%k:%M:%S)] \u@\h \w" "\n$"'

to your .bashrc file.

Cloning the Repository¶

To clone a copy of the SUNDIALS repository use one of the following commands:

Clone the repository with SSH Keys:

$ git clone ssh://git@mybitbucket.llnl.gov:7999/sundials/sunrepo.git

— OR —

Clone the repository with your OUN and AD password:

$ git clone https://YourOUN@mybitbucket.llnl.gov/scm/sundials/sunrepo.git

After cloning the repository you will be on the develop branch by default however, the develop and master branches are protected branches and can not be updated directly. In order to make changes to either of these branch you must create a new branch, make the desired modifications, and issue a pull request to have the changes merged into the parent branch. See the Workflow section for more information.

Workflow¶

This section describes the typical SUNDIALS workflow for adding new features and patching released code based on the Gitflow workflow. For details on setting up Git and cloning the repository see the Git Setup section. A list of helpful commands for working with Git is available in the Git Cheat Sheet.

Gitflow¶

In the Gitflow workflow there are two persistent branches in the repository, master and develop. The master branch contains the official release history while develop is an integration branch for new features. Work is not done directly on master or develop, rather changes to either branch are merged in through pull requests from short-lived branches that engage a single feature or issue. These working branches generally fall into two groups:

Feature branches for developing new features for future releases (typically created off of develop).
Maintenance branches for patching the current production release (typically created off of master).

New feature or maintenance branches are created and worked on until they are ready to be merged into master or develop. To merge the code changes into the desired branch a pull request is created and the code changes are reviewed by other team members. Once the pull request is approved, the changes will be merged and the working branch can be deleted. See the Example Workflow sections for an example of a typical workflow.

Naming Branches¶

To keep track of what work is in progress on different branches it is helpful to use short, descriptive branch names. When creating a new feature branch, use the feature/ label followed by a name for the feature e.g., feature/HypreVector for adding for a hypre vector. For maintenance branches, the branch label is usually bugfix/ or maintenance/ followed by the corresponding JIRA ticket name e.g., bugfix/SUNDIALS-123 or a name that describes the issue being addressed e.g., maintenance/documentation-updates.

Example Workflow¶

In the following example workflow PARENT refers the branch from which the current working branch was created i.e., the develop branch for feature branches and the master for maintenance branches.

To start working, checkout an existing branch or create a new one.
1. To work on an existing branch:
  1. Checkout the desired branch:
    $ git checkout <branch-name>
  2. Make sure the branch is up to date:
    $ git pull
2. To create a new branch to work on:
  1. Checkout the desired PARENT branch and make sure it’s up to date:
    $ git checkout PARENT $ git pull
  2. Create a new branch off of the PARENT branch:
    $ git checkout -b <branch-name> PARENT
  3. Push the new branch to the remote repo:
    $ git push -u origin <branch-name>
NOTE: When checking out a branch, any local changed must be committed (or stashed) prior to switching branches.
Modify files with your editor of choice:
```
$ emacs <some-path/file-name>
```
Stage the files you want to commit with:
```
$ git add <some-path/file-name>
```
Commit changes locally with either of the following commands depending on the detail needed in the commit message. See Commit Messages for guidelines when writing longer commit messages.
1. For short commit messages:
```
$ git commit -m "Short Description of the Commit"
```
— OR —
1. For longer commit messages:
```
$ git commit
```
  This opens the default system editor or the editor set in .gitconfig, see Git Configuration for more information.
Repeat the above modify, stage, and commit steps as needed to complete the work.
During the development cycle it is a good practice to periodically push local commits to the remote repo. To push your locally commited changes use:
```
$ git push
```
If changes exist on the remote copy of the branch that are not in your local version, Git will not allow you to push. You must first pull in the remote changes as described below and then push your local changes.
If you are collaborating with other developers on a feature you may need to update your local copy of a branch with changes from the remote version. To pull in remote changes use:
```
$ git pull
```
This will attempt to merge any remote commits into your local branch. If conflicts arise, Git will tell you. Follow the instructions in Resolving Conflicts to manually finish the merge. More experienced Git users may wish to use the --rebase option with git pull. See Rebasing for more information.

NOTE: Locally tracked changes must be committed (or stashed) prior to pulling remote changes.
As changes are merged into the PARENT branch, you may need to incorporate those changes into your working branch. To pull in changes from the remote PARENT branch use:
```
$ git pull origin PARENT
```
This will attempt to merge any changes on the remote PARENT branch into your local branch. If conflicts arise, Git will tell you. Follow the instructions in Resolving Conflicts to manually finish the merge. More experienced Git users may wish to use the --rebase option with git pull. See Rebasing for more information.

NOTE: Locally tracked changes must be committed (or stashed) prior to pulling remote changes.
Once the development work is complete make sure all changes have been pushed to the remote branch and open a pull request (PR) to start a code review for integrating the changes into the PARENT branch. See Pull Requests for more details on the opening a PR and the review process.

Commit Messages¶

The desired format for longer commit messages (more than a single line) is a short descriptive title followed by a blank line, and then a detailed commit message. For example, a commit making several changes to the ARKode initialization function might have the following message:

Retain history, remove LS/NLS init flag, skip init on reset

* move initializations inside FIRST_INIT
* retain error history on reset
* clear error/step history in SetInitStep
* skip stepper init checks on reset
* remove updates to ark LS and NLS init functions
* remove prototypes for old reinit utility function
* update docs

Resolving Conflicts¶

When updating the local copy of a branch with changes from the remote version or the PARENT branch merge conflicts may arise. In this case the conflicts can be resolved using either of the following approaches.

Manually resolve the conflicts in an editor:

View the status of the branch for more info on the files with conflicts:
```
$ git status
```
Use your editor of choice to resolve the conflicts
Add the resolved files:
```
$ git add <path/file-name>
```
Repeat the above steps until all conflicts are resolved
If conducting a merge, commit the merge changes with
```
$ git commit
```
or if rebasing, continue the rebase with
```
$ git rebase --continue
```
If desired, push the updated local brach to the remote repo with
```
$ git push
```

Alternatively, if you have setup a merge tool in your .gitconfig file (see Git Configuration for more details), then use resolve the conflicts with the merge tool:

Start the mergetool
```
$ git mergetool
```
Git will open each conflicted file in the merge tool one at a time. Resolve the conflicts, save the merged file, and close the merge tool. Git will then open the next conflicted file. As files are resolved and saved they will be automatically added to the merge/rebase commit.
When all conflicts are resolved, either commit the changes to the local branch if merging with
```
$ git commit
```
or if rebasing, continue the rebase with
```
$ git rebase --continue
```
If desired, push the updated local brach to the remote repo with
```
$ git push
```

Rebasing¶

Rebasing is an alternative to merging that replays commits one at a time on top of the HEAD of another branch (e.g., the remote copy of a local branch or the branch’s parent). This rewrites the commit history by reapplying old changes in a new commit to keep the history linear and avoid a merge commit. Rewriting history is potentially dangerous and should be done with caution.

As mentioned above when pulling changes the --rebase option can be used to perform a rebase rather than a merge e.g.,

$ git pull --rebase

If conflicts arise during the rebase (Git will tell you), follow the steps in Resolving Conflicts to resolve them. If you choose to continue working locally and later run git pull --rebase again, you will likely have to re-resolve conflicts that occurred in the previous rebase. In this case git rerere can be used to have Git remember how conflicts were resolved previously.

Generally, rebasing changes on the PARENT branch e.g., when running git pull --rebase origin PARENT is not recommended as all of the commits (local and remote) on the working branch will be replayed on the PARENT branch. As such this will rewrite commits that have been pushed to the remote repo and will therefore change the commit history that other developers have pulled and are working on.

Style Guide¶

This chapter covers the SUNDIALS style conventions for formatting source code, CMake files, and documentation files to ensure consistency and maintainability.

Coding Style¶

Formatting¶

Indentation¶

Spaces not tabs

Line Length¶

Loops¶

Comments¶

Function Comments¶

Implementation Comments¶

TODO Comments¶

Following the Google Style Guide [GoogleStyle], TODO comments are used to note code that is “temporary, a short-term solution, or good-enough but not perfect.”

A consistent TODO comment format provides an easy to search for keyword with details on how to get more information. TODO comments should start with TODO followed by a unique identifier, enclosed in parentheses, for the person most knowledgeable about the issue and a brief description of the TODO item. Generally, these comments should be used sparingly and are not a substitute for creating an issue or bug report. When applicable, the comment should include the relevant issue or bug report number.

Examples:

/* TODO(DJG): Update to new API in the next major release (Issue #256) */

Classes¶

Naming Convention for Vectors, Matrices, and Solvers¶

The SUNDIALS vector, matrix, linear solver, and nonlinear solver classes use the naming convention <short class name><method> for base class methods where each component of the name uses camel case. See Table 1 for examples.

Note

This naming convention only applies to the vector, matrix, and solver classes. All other classes should follow the naming convention described in Naming Convention for New Classes.

SUNDIALS base class naming convention examples for vectors, matrices, linear solvers and nonlinear solvers.¶
Base Class	Short Name	Operation	Method
`N_Vector`	`N_V`	Linear Sum	`N_VLinearSum`
`SUNMatrix`	`SUNMat`	Zero	`SUNMatZero`
`SUNLinearSolver`	`Setup`	Setup	`SUNLinSolSetup`
`SUNNonlinarSolver`	`Solve`	Solve	`SUNNonlinSolSolve`

Derived class implementations of the base class methods should follow the naming convention <short class name><method>_<implementation>. See Table 2 for examples.

SUNDIALS derived class naming convention examples for vectors, matrices, linear solvers and nonlinear solvers.¶
Derived Class	Base Class Method	Method Implementation
Serial	`N_VLinearSum`	`N_VLinearSum_Serial`
Dense	`SUNMatZero`	`SUNMatZero_Dense`
SPGMR	`SUNLinSolSetup`	`SUNLinSolSetup_SPGMR`
Newton	`SUNNonlinSolSolve`	`SUNNonlinSolSolve_Newton`

Implementation specific methods do not currently have a consistent naming convention across the different derived classes. When adding new methods to an existing class, follow the naming style used within that class. When adding a new derived class, use the same style as above for implementations of the base class method i.e., <short class name><method>_<implementation>.

Naming Convention for New Classes¶

All new base classes should use the naming convention <class name>_<method> for the base class methods. See Table 3 for examples.

SUNDIALS naming conventions for methods in new base classes.¶
Base Class	Operation	Method
`SUNMemoryHelper`	Alloc	`SUNMemoryHelper_Alloc`

Derived class implementations of the base class methods should follow the naming convention <class name>_<method>_<implementation>. See Table 4 for examples.

SUNDIALS naming conventions for derived class implementations of methods in new base classes.¶
Derived Class	Base Class Method	Method Implementation
CUDA	`SUNMemoryHelper_Alloc`	`SUNMemoryHelper_Alloc_Cuda`

Documentation Style¶

Style guide for RestructuredText with Sphinx.

File Structure¶

Generally, each chapter is a directory with a different file for each section.

Sections¶

Convention for which characters to use to denote a Chapter, Section, Subsection, SubSubSection, and paragraph.

Documenting Classes¶

Documenting Class Implementations¶

Documenting Functions¶

Documenting Macros¶

References¶

Add Citation and reference key style

Development¶

Development Checklist¶

When adding new functionality to SUNDIALS, in the form of bugfixes, new solvers, new solver options, new test problems, modifications to the SUNDIALS build system, etc. developers should adhere to the following checklist.

When adding new source code files, ensure that the corresponding CMakeLists.txt file(s) is/are updated to include your file(s). If your files depend on external libraries, emulate the CMake options used for other third party libraries to ensure that these files are only included when SUNDIALS is configured to use that library.
Configure SUNDIALS using the C flags -Wall -ansi -pedantic, to aid in catching compatibility issues on other platforms (Windows). When building, modify your file to remove any error/warning messages output during compilation of your code.
Configure your build with a minimal set of configuration options enabled (serial). Run make, make test, make install, and make test_install to ensure that everything functions smoothly, when no external libraries are supplied.
Configure your build with a maximal set of configuration options enabled (OpenMP, Pthreads, MPI, Lapack, KLU, etc.) and run make, make test, make install, and make test_install to ensure that everything functions smoothly when external libraries are supplied.
When implementing a bug-fix to an existing package/solver:
- If this change affects the user interface, update the documentation to describe the updated interface.
- For any problems that now fail when running “make test”, verify that the bugfix either made only cosmetic changes or improved the results, and update test output file in the examples/ directory.
When adding new solvers or new solver options:
- Update the documentation to include descriptions of your work. Ensure that the documentation also compiles (make ug in the relevant directory).
- Add a new example problem (or multiple problems) to the examples/ directory to demonstrate how to use your solver/option, and to include in SUNDIALS’ automated nightly tests.
- For any problems that now fail when running make test, verify that your updates either made only cosmetic changes or improved the results, and update test output in the examples/ directory.
When adding new test or example problems to the examples/ directory:
- Ensure that your new file has a unique name.
- After running make install, change to the installed examples/ directory and ensure that make succeeds, since the CMake-generated Makefile system differs from how the examples are built within SUNDIALS.
- Ensure that the reference output is included e.g., if a file foo.c is added, also add foo.out.
- Update the example problem documentation for to include a description of the new problem.
When adding any new files, update the corresponding package script in the scripts/ directory to include your file(s) within the distribution.
Use the debugging macros defined in src/sundials/sundials_debug.h where relevant and internal to SUNDIALS. Use the SUNDIALS_DEBUG macro to #ifdef out calls the sections of code which are for debugging purposes only. Additionally, the SUNDIALS_DEBUG_PRINTVEC macro should be used to #ifdef out calls to the generic vector print functions N_VPrint and N_VPrintFile used for debugging purposes.

Pull Requests¶

Once development on a working branch is ready to be incorporated into master or develop a pull request needs to created and the code changes reviewed by other developers before merging. The following sections describe the process for creating a new pull request, items a that should be consider when reviewing, and how to merge the pull request after approval.

Opening a Pull Request¶

When a branch is ready to be reviewed for integration into the master or develop branches follow the steps below to open a pull request:

Browse to https://mybitbucket.llnl.gov/projects/SUNDIALS/repos/sunrepo
Click on the branch icon on the left side of screen - you’ll see a list of all available branches
Click on your branch - you’ll see a ‘Compare’ screen that lets you pick a branch (source on top) to merge with another branch (target on bottom)
Select the desired branches and click ‘Create pull request’
Edit the title of the pull request (defaults to branch name), add a description, and select reviewers that can approve the request
Click ‘Create’

The selected reviewers will go over the changes in the pull request and may ask for additional changes before merging the branch. After the pull request is merged, delete the local copy the branch:

$ git checkout PARENT
$ git branch -D <branch-name>

Reviewing a Pull Request¶

When reviewing changes in a pull request consider the following questions:

Has the pull request has passed the regression tests?
Is all the necessary documentation included in the pull request?
Do the recent changes file and recent changes section in the user guides need to be updated?
If new files were created, do they need to be added to the tarscript?

Merging a Pull Request¶

Once a pull request has been approved by the necessary number of reviewers it is ready to be merged into the target branch. Before merging check that the answer to all of the following questions is yes.

Has the pull request has passed the regression tests?
Have all tasks in the pull request been completed?

Releases¶

This chapter discusses preparing a SUNDIALS release.

Versioning¶

SUNDIALS follows the semantic versioning scheme and each release is given a version number x.y.z where

x is the major version number and is incremented when the release includes an incompatible API change
y is the minor version number and is incremented when new functionality has been added and is backwards compatible with the prior version
z is the patch version and is incremented when the release only includes backwards compatible bug fixes

Additionally a pre-release versions will have -l.w appended to the version number i.e., x.y.z-l.w where

l is a pre-release label e.g., alpha, beta, or rc.
w is the pre-release version e.g, alpha.0, alpha.1, etc.

The convention for shared library versioning is libfoo.so.x.y.z. Note that there was no library versioning before sundials-2.2.0. The version information is specified by setting the VERSION and SOVERSION properties to the library target

add_library(foo file1.c file2.c)
set_target_properties(foo PROPERTIES VERSION x.y.z SOVERSION x)

and build system is responsible for creating the symlinks

libfoo.so   -> libfoo.so.x.y.z
libfoo.so.x -> libfoo.so.x.y.z

Note that we force SOVERSION to be the same as the major number for compatibility with the libtool versioning scheme (at least under Linux).

Pre-Release Tasks¶

This is a list of tasks that need to be done before a SUNDIALS release. The order is bottom-up starting with solver source files and ending with web pages.

Create release branch from trunk in the Git repository
If this is a major release, search the SUNDIALS code for ‘DEPRECATION NOTICE’ and ‘SUNDIALS_DEPRECATED’. All deprecated functions should be removed.
Regenerate the Fortran 2003 interfaces. It is possible nothing will be updated.
Update the “Changes in …” sections in all user guides. The changes should be sorted so that major new features are above bug fixes.
Update version numbers and release date information using the updateVerson.sh script. This will update the following files:
- CMakeLists.txt
- README.md
- src/arkode/README
- src/cvode/README
- src/cvodes/README
- src/ida/README
- src/idas/README
- src/kinsol/README
- doc/arkode/SphinxDocs/examples/source/conf.py
- doc/arkode/SphinxDocs/examples/source/References.rst
- doc/arkode/SphinxDocs/guide/source/conf.py
- doc/arkode/SphinxDocs/guide/source/History.rst
- doc/arkode/SphinxDocs/guide/source/References.rst
- doc/sundials/biblio.bib
- doc/sundials/sundials_release_history.tex
- doc/sundials/ug.tex
- scripts/tarscript
The ARKode LaTeX files doc/arkode/ARKode_example.tex and doc/arkode/ARKode.tex need to be regenerated and updated manually.

The following files are no longer maintaianed:
- html/main.html (This is no longer maintained as of at least 2016)
- sundialsTB/install_STB.m (This is no longer maintained as of 2016)
Update version numbers of third party libraries in the Install Guide in doc directory.
Create the new distribution tarballs using the tarscript shell script under the scripts directory. This also compiles the documents (user guides and example docs) and creates all tarballs in their final form, appropriate for uploading to the website.
Update Internal Drupal Web pages for SUNDIALS: https://computation-external.llnl.gov/user
1. Modify content (save edits on each page as you go)
  - Edit Main Page: https://computation-external.llnl.gov/projects/sundials
    - Update Release History page: https://computation-external.llnl.gov/projects/sundials/release-history
    - Add list of primary changes and child page containing full list of changes (this information is shared with “Changes in …” sections of user guides).
  - Edit Download Page: https://computation-external.llnl.gov/projects/sundials/sundials-software
    - Update main download table with new versions of solvers and new sizes
    - Upload new documentation (pdf) files.
    - Update Previous releases table with new entry for previous release of full SUNDIALS suite.
  - Edit Usage Notes Example Page if major release:
    - Upload new cvRoberts_dns_negsol.c, cvDisc_dns.c, and cvsRoberts_FSA_dns_Switch.c examples if necessary.
  - Edit FAQ if necessary: https://computation-external.llnl.gov/projects/sundials/faq
2. Once each sub page is complete, ask for team review of draft pages: https://computation-external.llnl.gov/projects/sundials
3. After team comments are included and saved, select the “Publishing options” button in the bottom left group of buttons on the draft page. Select the Moderation state reflecting the amount of required review then Save. This must be done for each page and is the final action before pages are uploaded for external release.
After final push, ensure web content and behavior is as expected on the main page: http://computation.llnl.gov/projects/sundials
Tag the release

Note as of 28 Aug 2019 the addresses web address above are still vaild but may change from “computation” to “computing” in the future.

Old steps for maintaianed code:

Create PDF files for SundialsTB:
1. Create the PDF doc for SundialsTB by running the Matlab program texdoc.m available in sundialsTB/doc.
2. The program uses the m2html toolbox, freely available. It creates doc files in PS and PDF formats as sundialsTB.ps and sundialsTB.pdf.
3. Follow Radu’s instructions in sundials/sundialsTB/doc/README_texdoc.

Appendix¶

Git Cheat Sheet¶

This section contains details helpful Git commands. For information on setting up Git see the Git Setup section and for the SUNDIALS Git workflow see the Workflow section.

Command Help

Print a list of common Git commands used in various situations
$ git --help
Print full man page for a Git command
$ git <git-command> --help
Print list of available options for a Git command
$ git <git-command> -h

Graphical Tools

Availability depends the Git installation

Visualize repo history
$ gitk
Graphical interface to Git
$ git gui

Branch

List all local branches (* denotes the current branch)
$ git branch
List all local branches with additional information
$ git branch -vv
List all remote branches
$ git branch -r
Create a new branch from an existing reference point (e.g., branch, commit hash, etc.)
$ git branch <new-branch-name> <reference>
Create a new branch from an existing reference point (e.g., branch, commit hash, etc.) and immediately checkout the new branch
$ git checkout -b <new-branch-name> <reference>

Add

Stage local changes to a file
$ git add <file-name>
Stage changes from a file in chunks
$ git add -p <file-name>
Unstage a committed file
$ git reset HEAD -- <file-name>
Discard local changes to a file and get the previously committed version
$ git checkout -- <file-name>
Discard local changes to a file in chunks
$ git checkout -p <file-name>

Commit

Commit staged files, this opens an editor for writing a commit message, an empty commit message will abort the commit
$ git commit
The desired format for a commit message is a short descriptive title followed by a blank line, and then a detailed commit message. For example, a commit making several changes to the ARKode initialization function might have the following message:
Retain history, remove LS/NLS init flag, skip init on reset

* move initializations inside FIRST_INIT
* retain error history on reset
* clear error/step history in SetInitStep
* skip stepper init checks on reset
* remove updates to ark LS and NLS init functions
* remove prototypes for old reinit utility function
* update docs
Commit staged files with short message
$ git commit -m "short commit message"
Amend the most recent commit (assuming it has not been pushed) to include the changes in this commit
$ git commit --amend
This is useful for adding forgotten changes to the last commit or for editing the commit message in the last commit (if no files are staged).

Push and Pull

Push a new branch and its commits to the remote repository and set the upstream tracking branch
$ git push -u origin <branch-name>
Push committed changes on the current branch to the remote repository
$ git push
Note: This is the same as git push origin <current-branch-name>.

Fetch and merge remote changes for the current branch
$ git pull
Note: This is the same as git pull origin <current-branch-name>.

Fetch and merge changes from a specific remote branch into the current branch
$ git pull origin <branch-name>
Fetch and rebase remote changes for the current branch
$ git pull --rebase
Note: Use caution when rebasing, see Rebasing for more details.

Fetch and rebase changes from a specific remote branch into the current branch
$ git pull --rebase origin <branch-name>
Note: Use caution when rebasing, see Rebasing for more details.

Merge

Merge a different local branch to your current branch
$ git merge <branch-name>
Resolve merge conflicts with a visual diff/merge tool
$ git mergetool
Find the newest common ancestor (fork point) of two reference points (branches, commits, etc.)
$ git merge-base <reference1> <reference2>

Rebase

Interactively rebase the committed but not pushed changes on the current branch
$ git rebase -i
Note: This command is useful for cleaning up the local commits history (e.g., reordering, squashing, updating commit messages, etc.) before pushing to the remote repository.

Rebase the commited but not pushed changes on the current branch and execute a given command (cmd) between each step in the rebase
$ git rebase -x "cmd"
Note: This command can be useful for debugging commits e.g., cmd can be used to run the test suite after each commit to find which commit causes the test suite to fail.

Cherry Pick

Apply a specific commit to the current branch
$ git cherry-pick <commit-hash>

Status and Differences

Print information on current local repo status including unstaged (changed and not added) files, staged (changed and added) files, and untracked files.
$ git status
Show all differences between unstaged changes and the current HEAD
$ git diff
Show the differences between unstaged changes and the current HEAD for a specific file
$ git diff <file-name>
Show differences between all staged files and current HEAD
$ git diff --staged
List all files changed in the current branch compared to different reference point (branch, commit hash, etc.)
$ git diff --name-only <reference>
Compare files between two branches
$ git diff <branch1>..<branch2> -- <file-name>
To view the differences going from the remote file to the local file
$ git diff remotename/branchname:remote/path/file1 local/path/file1
To view the differences going from the local file to the remote file
$ git diff HEAD:local/path/file1 remotename/branchname:remote/path/file1
To view the differences between files at any two reference points (e.g. branches, commit hashes, etc.)
$ git diff ref1:path/to/file1 ref2:path/to/file2
Note: In the above commands diff can be replaced with difftool if a visual diff tool has been setup with Git.

Log

Show commit log
$ git log
Show commit log for the last n commits
$ git log -n
Show commit log with more change information
$ git log --stat
Show all commits impacting a specific file
$ git log <file-name>

Stash

Save uncommitted changes in the stash
$ git stash
Save uncommitted changes in the stash with a stash message
$ git stash save "stash message"
View saved changes in the stash
$ git stash list
Apply to first set of stashed changes and remove the changes from the stash
$ git stash pop
Apply changes from the stash (does not remove changes from the stash)
$ git stash apply <stash-name>
Remove changes from the stash
$ git stash drop <stash-name>
Show difference between current HEAD and stashed work
$ git stash show -p <stash-name>

[GoogleStyle]

Google Style Guides