Introduction

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).

Obtaining and Installing Proteus

For learning and experimenting there is a Docker image. Proteus can be installed through conda with::

% conda install proteus -c conda-forge

Proteus is available as source from our public GitHub repository. For a development installation, the installation of dependencies and the compilation of Proteus from source is done with::

% git clone https://github.com/erdc/proteus
% cd proteus
% conda env create -f environment-dev.yml
% conda activate proteus-dev
% pip install -v -e .

Alternatively, if you already have compilers (C,C++, and Fortran!) installed on your system, you can install Proteus through hashdist with the following commands::

% git clone https://github.com/erdc/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.

Running

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.

Capabilities

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

  • 2D Dispersive 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 methods with various types of stabilization (entropy viscosity, variational multiscale, and algebraic 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.

Release Policy

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.

References

Indices and tables

Source Code Documentation

General