scikit-sundae 1.0.0rc3

SUNDIALS bindings to differential aglebraic equation solvers.

scikit-SUNDAE

     

Summary

scikit-SUNDAE provides Python bindings to SUNDIALS integrators. The implicit differential algebraic (IDA) solver and C-based variable-coefficient ordinary differential equations (CVODE) solver are both included.

The name SUNDAE combines (SUN)DIALS and DAE, which stands for differential algebraic equations. Solvers specific to DAE problems are not frequently available in Python. An ordinary differential equation (ODE) solver is also included for completeness. ODEs can be categorized as a subset of DAEs (i.e., DAEs with no algebraic constraints).

Installation

scikit-SUNDAE is installable via either pip or conda. To install from PyPI use the following command.

pip install scikit-sundae

If you prefer using the conda package manager, you can install scikit-SUNDAE from the conda-forge channel using the command below.

conda install -c conda-forge scikit-sundae

Both sources contain binary installations. If your combination of operating system and CPU architecture is not supported, please submit an issue to let us know. If you'd prefer to build from source, please see the documentation.

Get Started

You are now ready to start solving. Run one of the following examples to check your installation. Afterward, check out the documentation for a full list of options (including event functions), detailed examples, and more.

# Use the CVODE integrator to solve the Van der Pol equation

from sksundae.cvode import CVODE
import matplotlib.pyplot as plt

def rhsfn(t, y, yp):
    yp[0] = y[1]
    yp[1] = 1000*(1 - y[0]**2)*y[1] - y[0]

solver = CVODE(rhsfn)
soln = solver.solve([0, 3000], [2, 0])

plt.plot(soln.t, soln.y[:, 0])
plt.show()

The CVODE solver demonstrated above is only capable of solving pure ODEs. The constant parameters and time span used above match an example given by MATLAB for easy comparison. If you are trying to solve a DAE, you will want to use the IDA solver instead. A minimal DAE example is given below for the Robertson problem. As with the CVODE example, the parameters below are chosen to match an online MATLAB example for easy comparison.

# Use the IDA integrator to solve the Robertson problem

from sksundae.ida import IDA
import matplotlib.pyplot as plt

def resfn(t, y, yp, res):
    res[0] = yp[0] + 0.04*y[0] - 1e4*y[1]*y[2]
    res[1] = yp[1] - 0.04*y[0] + 1e4*y[1]*y[2] + 3e7*y[1]**2
    res[2] = y[0] + y[1] + y[2] - 1

solver = IDA(resfn, algebraic_idx=[2], calc_initcond='yp0')
soln = solver.solve([4e-6, 4e6], [1, 0, 0], [0, 0, 0])

plt.plot(soln.t, soln.y)
plt.legend(['y0', 'y1', 'y2'])
plt.show()

Notes:

• If you are new to Python, check out Spyder IDE. Spyder is a powerful interactive development environment (IDE) that can make programming in Python more approachable to new users.
• Check the solve_ivp documentation from scipy or the scipy-dae package repository if you are looking for common examples to test out and compare against. Translating an example from another package can help you learn how to use scikit-SUNDAE before trying to solve more challenging problems.

Citing this Work

This work was authored by researchers at the National Renewable Energy Laboratory (NREL). The project is tracked in NREL's software records under SWR-24-137 and has a DOI available for citing the work. If you use use this package in your work, please include the following citation:

Placeholder... waiting for DOI.

For convenience, we also provide the following for your BibTex:

@misc{Randall2024,
  title = {{scikit-SUNDAE: Python bindings to SUNDIALS DAE solvers}},
  author = {Randall, Corey R.},
  year = {2024},
  doi = {placeholder... waiting for DOI},
  url = {https://github.com/NREL/scikit-sundae},
}

Acknowledgements

scikit-SUNDAE was originally inspired by scikits.odes which also offers Python bindings to SUNDIALS. The API for scikit-SUNDAE was mostly adopted from scikits.odes; however, all of our source code is original. If you are comparing the two:

1. scikits.odes: includes iterative solvers and some optional solvers (e.g., LAPACK). The package only provides source distributions, so users must configure and compile SUNDAILS on their own.
2. scikit-SUNDAE: includes more flexible events function capabilities (e.g., direction detection and terminal flags), scipy-like output, and provides both binary and source distributions. Iterative and optional solvers are not available.

Our binary distributions include pre-compiled dynamic SUNDIALS libraries. These are self-contained and will not affect other, existing installations you may already have. To be in compliance with SUNDIALS distribution requirements, all scikit-SUNDAE distributions include a copy of the SUNDIALS license.

Contributing

If you'd like to contribute to this package, please look through the existing issues. If the bug you've caught or the feature you'd like to add isn't already reported, please submit a new issue. You should also read through the developer guidelines if you plan to work on the issue yourself.

Disclaimer

This work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE). The views expressed in the repository do not necessarily represent the views of the DOE or the U.S. Government.