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
An Unstructured Finite Element Model for Incompressible Two-Phase Flow Based on a Monolithic Conservative Level Set Method (2020) M. Quezada de Luna, J. H. Collins, and C.E. Kees, International Journal for Numerical Methods in Fluids.
Robust explicit relaxation technique for solving the Green-Naghdi equations (2019) J.-L. Guermond, B. Popov, E. Tovar, C.E. Kees, Journal of Computational Physics
Preconditioners for Two-Phase Incompressible Navier-Stokes Flow (2019) N. Bootland, C.E. Kees, A. Wathen, A. Bentley SIAM Journal on Scientific Computing, In Press.
Modeling Sediment Transport in Three-Phase Surface Water Systems (2019) C.T. Miller, W.G. Gray, C.E. Kees, I.V. Rybak, B.J. Shepherd, Journal of Hydraulic Engineering
Fast Random Wave Generation in Numerical Tanks (2019) A. Dimakopoulos, T. de Lataillade, C.E. Kees, Proceedings of the Institution of Civil Engineers - Engineering and Computational Mechanics, 1-29.
A Partition of Unity Approach to Adaptivity and Limiting in Continuous Finite Element Methods (2019) D. Kuzmin, M. Quezada de Luna, C.E. Kees, Computers and Mathematics with Applications.
Simulating Oscillatory and Sliding Displacements of Caisson Breakwaters Using a Coupled Approach (2019) G. Cozzuto, A. Dimakopoulos, T. de Lataillade, P.O. Morillas, and C.E. Kees, Journal of Waterway, Port, Coastal, and Ocean Engineering.
A Monolithic Conservative Level Set Method with Built-In Redistancing (2019) M. Quezada de Luna, D. Kuzmin, C.E. Kees, Journal of Computational Physics, 379, 262-278.
Computational Model for Wave Attenuation by Flexible Vegetation (2018) S.A. Mattis, C.E. Kees, M.V. Wei, A. Dimakopoulos, and C.N. Dawson, Journal of Waterway, Port, Coastal, and Ocean Engineering 145(1), p.04018033.
Well-Balanced Second-Order Finite Element Approximation of the Shallow Water Equations with Friction (2018) J.L. Guermond, M.Q. de Luna, B. Popov, C.E. Kees, and M.W. Farthing SIAM Journal on Scientific Computing 40(6), A3873-A3901.
Dual-Scale Galerkin Methods for Darcy Flow (2018) G. Wang, G. Scovazzi, L. Nouveau, C.E. Kees, Simone Rossi, O. Colomes, and A. Main (2018) Journal of Computational Physics 354, 111-134.
Implementation details of the level set two-phase Navier-Stokes equations in Proteus (2017) A. Bentley, N. Bootland, A. Wathen, C. Kees, Technical-Report-TR2017-10-ab.nb.aw.ck.
Evaluation of Galerkin and Petrov-Galerkin Model Reduction for Finite Element Approximations of the Shallow Water Equations (2017) A. Lozovsky, M. W. Farthing, and C.E. Kees, Computational Methods in Applied Mechanics and Engineering 318, 537-571.
POD-Based Model Reduction for Stabilized Finite Element Approximations of Shallow Water Flows (2016) A. Lozovskiy, M.W. Farthing, C.E. Kees, E. Gildin Journal of Computational and Applied Mathematics, 302, 50-70.
An Immersed Structure Approach for Fluid-Vegetation Interaction (2015) S.A. Mattis, C.N. Dawson, C.E. Kees, M.W. Farthing, Advances in Water Resources, 80,1-16.
Finite Element Methods for Variable Density Flow And Solute Transport (2013) T.J. Povich, C.N. Dawson, M.W. Farthing, C.E. Kees Computational Geosciences 17(3), 529-549.
Numerical simulation of water resources problems: Models, methods, and trends (2013) Cass T. Miller, Clint N. Dawson, Matthew W. Farthing, Thomas Y. Hou, Jingfang Huang, Christopher E. Kees, C.T. Kelley, and Hans Petter Langtangen Advances in Water Resources, 51, 405-437,
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