[Opm] Where to start to learn the OPM FLOW code ?

[Atgeirr Rasmussen]

26. aug. 2016 kl. 07.24 skrev Ye Li <yli15 at uwyo.edu<mailto:yli15 at uwyo.edu>>:


Hi, all:

Thanks for creating OPM, such a meaningful project.

I have several years experience with reservoir simulation.  I want to read the code of OPM to learn the "black box" behind the reservoir simulation. However, I am stuck and do not know where I should start.

I went through several modules, like ope-common-master, opm-core-master, opt-grid-master, and etc..

If I want to learn the code of OPM FLOW, for example, where should I start and how to follow?

Thanks for your time, and I do appreciate.


Thanks for your kind words, and welcome to the Opm community!

The code is, as you have found out, spread out over several modules. I'll try to give a brief overview
of the most important parts of the simulator, and where to find the code that is used. Be aware that
we are continuously refactoring and changing the code to improve performance or extensibility, or
to add features.


0. Startup

The actual main() function of the simulator is rather small. Most of the actual setup is done in the
class FlowMain in opm-simulators. After setup, it calls the run() method of a simulator class,
see the SimulatorBase class to see how it works.



1. Input

There are two sources of input: the command line (or parameter file) and a simulation deck in Eclipse format.
The most important is the deck, and if you don't need or want to change any of the defaults you can do with
just the deck.

The opm-parser module handles the deck input. The classes Parser and Deck read, parse and store the deck.
In order to access the content of the deck we prefer to use the EclipseState class rather than the Deck directly,
this is because the EclipseState provides the final state of important properties like pore volumes etc. If we were
to use the Deck directly we would have to account for all kinds of manipulation with multipliers and BOX keywords,
but the EclipseState already does all of that. (You can think of a deck as a state machine, and the EclipseState
provides the final state after all manipulations.) The EclipseState also provides the Schedule class, which contains the
well schedule and properties.

The command line parameters are handled by the ParameterGroup class from opm-core.



2. Properties

The opm-material module provides the low-level fluid properties, both saturation properties like
relative permeability and capillary pressure, and pvt properties like viscosity and formation volume
factors. For pvt the important class is FluidSystems::Blackoil (found in BlackoilFluidSystem.hpp),
which provides the features needed (saturated and unsaturated property values for example).

The Flow simulator accesses these properties through a facade class. This is in opm-simulators
and is called BlackoilPropsAdFromDeck.



3. Initialization

For Flow, this is done by the initStateEquil() function in opm-core. It is a rather complicated system though,
and we'd like to simplify this.



4. Solving

All of this is in the opm-simulators module. The basic nonlinear solver machinery is in the class NonlinearSolver,
but this class leaves great freedom to the model class used (by calling its nonlinearIteration() method).

The current class implementing the blackoil model is the BlackoilModel class. However, in order to support extensions
to the usual model all the important stuff is actually in the BlackoilModelBase class (extensions include polymer and solvent).
This class is one of the largest in OPM, but if you want to take a look at the assembly process you could read the assemble()
function and see what it calls (or even better: step through it in a debugger), most of it is quite straightforward.
This class uses automatic differentiation (AD) to automatically assemble the Jacobian matrices as we compute the nonlinear
residual. The AD capability is provided by the AutoDiffBlock class.

Finally (in each nonlinear iteration) the residual and Jacobians are passed to a customized linear solvers. The main one currently
used is the class NewtonIterationBlackoilInterleaved, which structures the linear system in such a way that all unknowns
associated with a cell are clustered together.



5. Output

Result output is provided by the opm-output module, especially the EclipseWriter class that provides Eclipse-standard binary output of
summary and restart files. This facility is being worked on quite heavily right now, with the goal of providing a very flexible output
capability, which is completely configurable from the deck.

Log output (to the terminal and log files) is provided by the OpmLog facility, which is implemented in the opm-common module.
You will see some output to the terminal, some more to a .PRT file and if you are really curious you can look at the (hidden to avoid
confusion for regular users) debug output file named .CASENAME.DEBUG — notice the period at the start of the name.



I hope that gets you started. If you have any further questions, feel free to ask. Good luck!


Atgeirr
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <//opm-project.org/pipermail/opm/attachments/20160826/d7f3289e/attachment.html>