A Python toolkit for computational methods and simulation

Proteus is a Python package for rapidly developing computer models and numerical methods. It is focused on models of continuum mechanical processes described by partial differential equations and on discretizations and solvers for computing approximate solutions to these equations. Proteus consists of a collection of Python modules and scripts. Proteus also uses several C, C++, and Fortran libraries, which are either external open source packages or part of Proteus, and several open source Python packages.

The design of Proteus is organized around two goals:

- Make it easy to solve new model equations with existing numerical methods
- Make it easy to solve existing model equations with new numerical methods

We want to improve the development process for models *and*
methods. Proteus is not intended to be an expert system for solving
partial differential equations. In fact, effective numerical methods
are often physics-based. Nevertheless many physical models are
mathematically represented by the same small set of differential
operators, and effective numerical methods can be developed with minor
adjustments to existing methods. The problem with much existing
software is that the physics and numerics are completely intertwined,
which makes it difficult to extend (and maintain). In Proteus the
description of the physical model and initial-boundary value problems
are nearly “method agnostic”. This approach has been used in the
developement of a variety of mathematical models and numerical
methods, both of which are described in more detail below
(Capabilities).

For learning and experimenting there is an anonymous temporary Jupyter notebook server at try.proteustoolkit.org:8000.

Proteus is available as source from our public GitHub repository. If you already have compilers (C,C++, and Fortran!) and Git installed on your system, you can install Proteus with the following commands.:

```
% git clone https://github.com/erdc-cm/proteus
% cd proteus
% make develop
% make test
```

More information is available on our Wiki, and you can ask for help on the Developers’ Mailing List.

If you have successfully compiled and tested Proteus then you should be able to do:

```
% cd $PROTEUS/tests/ci
% $PROTEUS_PREFIX/bin/parun poisson_3d_p.py poisson_3d_c0p1_n.py
```

The solution will be saved in a file ending in .xmf, which can be opened with ParaView or Ensight.

Test problems and some analytical solutions have been implemented for

- Poisson’s equation
- The heat equation
- Linear advection-diffusion-reaction equations
- Singly degenerate nonlinear advection-diffusion-reaction equations (including various forms of Burger’s equation)
- Doubly degenerate nonlinear advection-diffusion-reaction equations
- The eikonal (signed distance) equation
- The diffusive wave equations for overland flow
- 1D and 2D Shallow Water Equations
- Richards’ equation (mass conservative head- and saturation-based)
- Two-phase flow in porous media with diffuse interface (fully coupled and IMPES formulations)
- Two-phase flow in porous media with a sharp interface (level set formulation)
- Stokes equations
- Navier-Stokes equations
- Reynolds-Averged Navier-Stokes equations
- Two-phase Stokes/Navier-Stokes/RANS flow with a sharp interface (level set/VOF formulation)
- Linear elasticity

These problems are solved on unstructured simplicial meshes. Simple meshes can be generated with tools included with Proteus, and more complex meshes can by imported from other mesh generators. The finite elements implemented are

Classical and vartiational multiscale methods

- \(C_0 P_1\)
- \(C_0 P_2\)
- \(C_0 Q_1\)
- \(C_0 Q_2\)

Discontinuous Galerkin methods

- \(C_{-1} P_0\)
- \(C_{-1} P_1\) (Lagrange Basis)
- \(C_{-1} P_2\) (Lagrange Basis)
- \(C_{-1} P_k\) (Monomial Basis)

Non-conforming and mixed methods

- \(P_1\) non-conforming
- \(C_0 P_1 C_0 P_2\) Taylor-Hood

The time integration methods are

- Backward Euler
- Forward Euler
- \(\Theta\) Methods
- Strong Stability Preserving Runge-Kutta Methods
- Adaptive BDF Methods
- Pseudo-transient continuation

The linear solvers are

- Jacobi
- Gauss-Seidel
- Alternating Schwarz
- Full Multigrid
- Wrappers to LAPACK, SuperLU, and PETSc

The nonlinear solvers are

- Jacobi
- Gauss-Seidel
- Alternating Schwarz
- Newton’s method
- Nonlinear Multigrid (Full Approximation Scheme)
- Fast Marching and Fast Sweeping

Additional tools are included for pre- and post-processings meshes and solutions files generated by Proteus and other models, including methods for obtaining locally-conservative velocity fields from \(C_0\) finite elements.

The releases are numbered major.minor.revision

- A revision increment indicates a bug fix or extension that shouldn’t break any models working with the same major.minor number.
- A minor increment introduces significant new functionality but is mostly backward compatible
- A major increment may require changes to input files and significantly change the underlying Proteus implementation.

These are not hard and fast rules, and there is no time table for releases.

- Numerical modeling of drag for flow through vegetated domains and
porous structures (2012)
S.A. Mattis, C. N. Dawson, C. E. Kees, and M. W. Farthing,
*Advances in Water Resources*, 39, pp44-59 - Parallel Computational Methods and Simulation for Coastal and
Hydraulic Applications Using the Proteus Toolkit
(2011) C. E. Kees and M. W. Farthing (2011)
*Supercomputing11: Proceedings of the PyHPC11 Workshop* - A Conservative Level Set Method for Variable-Order Approximations
and Unstructured Meshes (2011) C.E. Kees,
I. Akkerman, Y. Bazilevs, and M. W. Farthing
*Journal of Computational Physics*230(12), pp4536–4558 - Locally Conservative, Stabilized Finite Element Methods For
Variably Saturated Flow (2008) Kees, C.E.,
M. W. Farthing, and C. N. Dawson,
*Computer Methods in Applied Mechanics and Engineering*, 197, pp4610-4625 - Locally Conservative, Stabilized Finite Element Methods for a Class
of Variable Coefficient Navier-Stokes Equations (2009)
C. E. Kees, M. W. Farthing, and M. T. Fong,
*ERDC/CHL TR-09-12* - Evaluating Finite Element Methods for the Level Set Equation (2009)
M. W. Farthing and C. E. Kees,
*ERDC/CHL TR-09-11* - A Review of Methods for Moving Boundary Problems (2009)
C. E. Kees, M. W. Farthing, T. C. Lackey, and R. C. Berger,
*ERDC/CHL TR-09-10* - Implementation of Discontinuous Galerkin Methods for the Level Set
Equation on Unstructured Meshes
(2008) M. W. Farthing and C. E. Kees,
*ERDC/CHL CHETN-XIII-2*