JutulDarcy.jl - reservoir simulation and porous media flow in Julia
Documentation for JutulDarcy.jl. The documentation is currently limited to docstrings and a series of examples. The examples are sorted by complexity. We suggest you start with Gravity segregation example.
JutulDarcy builds upon the general features found in Jutul.jl. You may also find it useful to look at the Jutul.jl documentation.
Package docstring
JutulDarcy.JutulDarcy
— ModuleReservoir simulation in Julia
JutulDarcy.jl: Darcy-scale and subsurface flow (CO2 sequestration, gas/H2 storage, oil/gas fields) using Jutul.jl developed by the Applied Computational Science group at SINTEF Digital.
Key features
JutulDarcy is a general purpose porous media simulator with high performance written in Julia. It is fully differentiable with respect to forces and discretization parameters.
Physical systems
- Immiscible multi-phase flow
- Black-oil type models with support for both dissolved vapor (Rs) and vaporized liquid (Rv)
- Equation-of-state compositional flow with up to three phases and any number of components
All solvers can incorporate general multisegment wells with rigorous mass balance, friction pressure loss, complex well limits and time-dependent controls.
Architecture
- Written in pure Julia, with automatic differentiation and dynamic sparsity detection
- Support for sensitivities with respect to any model parameters using the adjoint method
- High performance assembly and linear solvers, with support for two-stage CPR BILU(0)-CPR Krylov solvers
- MPI support with domain decomposition and BoomerAMG-CPR solver with automatic METIS partitioning
Input/output and workflow tools
- Unstructured grids and complex cases input from the Matlab Reservoir Simulation Toolbox (MRST) using the
jutul
module - Experimental support for reading in and running .DATA files with corner point grids
- 3D visualization of grids and wells by loading a Makie.jl backend (requires Julia 1.9,
GLMakie
for interactivity) - Interactive plotting of well curves
The compositional simulator has been matched against commercial offerings, AD-GPRS and MRST. The blackoil simulator has been validated on the standard SPE benchmarks (SPE1, SPE9, ...).
Example run times on benchmarks
Name | Cells | Report steps | Preconditioner | Time [s] |
---|---|---|---|---|
SPE1CASE2 | 300 | 120 | block-ILU(0) | 0.30 |
SPE9 | 9000 | 35 | block-ILU(0) | 3.41 |
Egg | 18553 | 123 | CPR-block-ILU(0) | 8.60 |
Simulated with default julia
, no threads. Runtime with single-threaded HYPRE on the full SPE10 model 2 model is about 20 minutes with default settings and strict mass-balance tolerances and less than 4 minutes for realization 1 of the OLYMPUS optimization benchmark challenge.
A few of the packages used by Jutul and JutulDarcy
Jutul builds upon many of the excellent packages in the Julia ecosystem. Here are a few of them, and what they are used for:
- ForwardDiff.jl implements the Dual number class used throughout the code
- SparsityTracing.jl provides sparsity detection inside Jutul
- Krylov.jl provides the iterative linear solvers
- ILUZero.jl for ILU(0) preconditioners
- AlgebraicMultigrid.jl for AMG preconditioners
- HYPRE.jl for robust AMG preconditioners with MPI support
- PartitionedArrays.jl for MPI assembly and linear solve
- Tullio.jl for automatically optimized loops and Polyester.jl for lightweight threads
- TimerOutputs.jl and ProgressMeter.jl gives nice output to terminal
- Makie.jl is used for the visualization features
- MultiComponentFlash.jl provides many of the compositional features
...and many more, both directly in the Project.toml file and indirectly!
Getting started
Install Julia and add the package to your environment of choice:
using Pkg
Pkg.add("CairoMakie")
Pkg.add("Jutul")
Pkg.add("JutulDarcy")
You can then run any of the examples in the examples
directory by including them.
Additional examples and further reading
The documentation is still work in progress, but contains a fair bit of useful information. In addition, see the examples folder for more information. Some functionality is also demonstrated in the tests.
Internals and undocumented functions are subject to change at this time. However, the main interface for the reservoir simulator itself seen in the examples should be fairly stable.
Module exports:
AqueousPhase
BlackOilUnknown
BlackOilX
BottomHolePressureTarget
BrooksCoreyRelativePermeabilities
CPRPreconditioner
ConstMuBTable
ConstantCompressibilityDensities
DeckPhaseMassDensities
DeckPhaseViscosities
DeckShrinkageFactors
DisabledControl
DisabledTarget
FlowBoundaryCondition
HistoricalReservoirVoidageTarget
ImmiscibleSaturation
ImmiscibleSystem
InjectorControl
KValueWrapper
LiquidPhase
MassSource
MinimalTPFAGrid
MixedWellSegmentFlow
MuBTable
MultiPhaseCompositionalSystemLV
MultiPhaseSystem
MultiSegmentWell
OverallMoleFractions
PerforationMask
Perforations
PhaseMassDensities
PhaseMassFractions
PhaseRelativePermeability
PotentialDropBalanceWell
Pressure
ProducerControl
RelativePermeabilities
ReservoirSimResult
ReservoirVoidageTarget
Saturations
SegmentWellBoreFrictionHB
SinglePhaseRateTarget
SinglePhaseSystem
SourceTerm
StandardBlackOilSystem
StandardVolumeSource
SurfaceGasRateTarget
SurfaceLiquidRateTarget
SurfaceOilRateTarget
SurfaceWaterRateTarget
TabulatedSimpleRelativePermeabilities
ThermalSystem
ThreePhaseCompositionalDensitiesLV
ThreePhaseLBCViscositiesLV
TotalMass
TotalMassFlux
TotalMassVelocityMassFractionsFlow
TotalMasses
TotalRateTarget
TotalSurfaceMassRate
VaporPhase
VolumeSource
WellDomain
WellGroup
Wells
available_well_targets
component_mass_fluxes!
compute_peaceman_index
discretized_domain_tpfv_flow
discretized_domain_well
fluid_volume
full_well_outputs
get_1d_reservoir
get_test_setup
get_well_from_mrst_data
number_of_phases
plot_reservoir
plot_reservoir_simulation_result
plot_well!
plot_well_results
pore_volume
reservoir_domain
reservoir_linsolve
reservoir_model
reservoir_system
segment_pressure_drop
setup_case_from_data_file
setup_case_from_mrst
setup_reservoir_forces
setup_reservoir_model
setup_reservoir_simulator
setup_reservoir_simulator_parray
setup_reservoir_state
setup_vertical_well
setup_well
simulate_data_file
simulate_mrst_case
simulate_reservoir
simulate_reservoir_parray
table_to_relperm
update_total_masses!
well_mismatch
well_output
well_symbols
wellgroup_symbols
Index
JutulDarcy.JutulDarcy
Jutul.AMGPreconditioner
Jutul.BlockMajorLayout
Jutul.BoundaryFaces
Jutul.CartesianMesh
Jutul.Cells
Jutul.CoarseMesh
Jutul.CompactAutoDiffCache
Jutul.DataDomain
Jutul.DefaultContext
Jutul.DiscretizedDomain
Jutul.EntityMajorLayout
Jutul.EquationMajorLayout
Jutul.EquationSet
Jutul.FaceMap
Jutul.Faces
Jutul.FlowDiscretization
Jutul.FractionVariables
Jutul.GenericKrylov
Jutul.GlobalSet
Jutul.GroupWisePreconditioner
Jutul.HalfFaces
Jutul.HelperSimulator
Jutul.ILUZeroPreconditioner
Jutul.IndirectionMap
Jutul.JacobiPreconditioner
Jutul.JutulAutoDiffCache
Jutul.JutulCase
Jutul.JutulConfig
Jutul.JutulContext
Jutul.JutulDiscretization
Jutul.JutulDiscretization
Jutul.JutulDomain
Jutul.JutulEntity
Jutul.JutulEquation
Jutul.JutulForce
Jutul.JutulMatrixLayout
Jutul.JutulMesh
Jutul.JutulSystem
Jutul.JutulVariables
Jutul.LUPreconditioner
Jutul.LUSolver
Jutul.MRSTWrapMesh
Jutul.MRSTWrapMesh
Jutul.MultiModel
Jutul.NoEntity
Jutul.Nodes
Jutul.ParallelCSRContext
Jutul.SPAI0Preconditioner
Jutul.SPU
Jutul.ScalarVariable
Jutul.SimulationModel
Jutul.SimulationModel
Jutul.Simulator
Jutul.SparsityTracingWrapper
Jutul.TPFA
Jutul.TwoPointFiniteVolumeGeometry
Jutul.UnstructuredMesh
Jutul.UnstructuredMesh
Jutul.VariableSet
Jutul.VectorVariables
JutulDarcy.AqueousPhase
JutulDarcy.BlackOilUnknown
JutulDarcy.BlackOilX
JutulDarcy.BottomHolePressureTarget
JutulDarcy.BrooksCoreyRelativePermeabilities
JutulDarcy.CPRPreconditioner
JutulDarcy.ConstantCompressibilityDensities
JutulDarcy.DeckPhaseViscosities
JutulDarcy.DeckShrinkageFactors
JutulDarcy.DisabledControl
JutulDarcy.DisabledTarget
JutulDarcy.FlowBoundaryCondition
JutulDarcy.HistoricalReservoirVoidageTarget
JutulDarcy.ImmiscibleSaturation
JutulDarcy.ImmiscibleSystem
JutulDarcy.InjectorControl
JutulDarcy.LiquidPhase
JutulDarcy.MultiPhaseCompositionalSystemLV
JutulDarcy.MultiSegmentWell
JutulDarcy.OverallMoleFractions
JutulDarcy.PerforationMask
JutulDarcy.PhaseMassDensities
JutulDarcy.PhaseMassFractions
JutulDarcy.PhaseRelativePermeability
JutulDarcy.Pressure
JutulDarcy.ProducerControl
JutulDarcy.RelativePermeabilities
JutulDarcy.ReservoirRelativePermeabilities
JutulDarcy.ReservoirSimResult
JutulDarcy.ReservoirVoidageTarget
JutulDarcy.Saturations
JutulDarcy.SimpleWell
JutulDarcy.SinglePhaseRateTarget
JutulDarcy.SinglePhaseSystem
JutulDarcy.SourceTerm
JutulDarcy.StandardBlackOilSystem
JutulDarcy.SurfaceGasRateTarget
JutulDarcy.SurfaceLiquidRateTarget
JutulDarcy.SurfaceOilRateTarget
JutulDarcy.SurfaceWaterRateTarget
JutulDarcy.ThermalSystem
JutulDarcy.TotalMass
JutulDarcy.TotalMassFlux
JutulDarcy.TotalMasses
JutulDarcy.TotalRateTarget
JutulDarcy.TotalSurfaceMassRate
JutulDarcy.Transmissibilities
JutulDarcy.VaporPhase
JutulDarcy.WellGroup
Jutul.absolute_increment_limit
Jutul.add_option!
Jutul.align_to_jacobian!
Jutul.align_to_jacobian!
Jutul.allocate_array_ad
Jutul.allocate_array_ad
Jutul.allocate_array_ad
Jutul.apply_forces!
Jutul.apply_forces_to_equation!
Jutul.apply_forces_to_equation!
Jutul.as_value
Jutul.associated_entity
Jutul.associated_entity
Jutul.cell_dims
Jutul.cell_index
Jutul.compress_timesteps
Jutul.compress_timesteps
Jutul.compute_boundary_trans
Jutul.compute_face_trans
Jutul.compute_half_face_trans
Jutul.convergence_criterion
Jutul.convert_from_si
Jutul.convert_state_ad
Jutul.convert_to_si
Jutul.coord_offset
Jutul.declare_pattern
Jutul.declare_sparsity
Jutul.degrees_of_freedom_per_entity
Jutul.descalarize_primary_variable!
Jutul.descalarize_primary_variables!
Jutul.dim
Jutul.expand_to_ministeps
Jutul.expand_to_ministeps
Jutul.extra_debug_output!
Jutul.extract_submesh
Jutul.full_cell
Jutul.get_1d_interpolator
Jutul.get_2d_interpolator
Jutul.get_ad_entity_scalar
Jutul.get_dependencies
Jutul.get_diagonal_entries
Jutul.get_entity_tag
Jutul.get_entries
Jutul.get_entries
Jutul.get_mesh_entity_tag
Jutul.get_parameters
Jutul.get_primary_variable_ordered_entities
Jutul.get_primary_variables
Jutul.get_secondary_variables
Jutul.get_sparse_arguments
Jutul.get_tstr
Jutul.get_variable
Jutul.get_variables
Jutul.global_cell
Jutul.global_face
Jutul.initialize_context!
Jutul.initialize_extra_state_fields!
Jutul.initialize_storage!
Jutul.initialize_variable_value
Jutul.interior_cell
Jutul.interpolation_constant_lookup
Jutul.jutul_output_path
Jutul.linear_timestep_selection
Jutul.load_balanced_endpoint
Jutul.load_balanced_interval
Jutul.local_ad
Jutul.local_cell
Jutul.local_face
Jutul.local_residual_view
Jutul.maximum_value
Jutul.merge_step_report_errors
Jutul.minimum_value
Jutul.model_accumulation!
Jutul.model_residual
Jutul.model_residual!
Jutul.number_of_cells
Jutul.number_of_degrees_of_freedom
Jutul.number_of_entities
Jutul.number_of_entities
Jutul.number_of_entities
Jutul.number_of_entities
Jutul.number_of_entities
Jutul.number_of_equations
Jutul.number_of_equations_per_entity
Jutul.number_of_faces
Jutul.number_of_partials_per_entity
Jutul.number_of_values
Jutul.numerical_eltype
Jutul.numerical_type
Jutul.partition
Jutul.partition_hypergraph
Jutul.physical_representation
Jutul.physical_representation
Jutul.physical_representation
Jutul.physical_representation
Jutul.pick_next_timestep
Jutul.prepare_step_storage
Jutul.read_results
Jutul.relative_increment_limit
Jutul.replace_variables!
Jutul.scalarize_primary_variable
Jutul.scalarize_primary_variables
Jutul.scalarize_primary_variables!
Jutul.scalarized_primary_variable_type
Jutul.set_default_tolerances
Jutul.set_parameters!
Jutul.set_primary_variables!
Jutul.set_secondary_variables!
Jutul.setup_adjoint_storage
Jutul.setup_forces
Jutul.setup_parameter_optimization
Jutul.setup_parameters
Jutul.setup_partitioner_hypergraph
Jutul.setup_state
Jutul.setup_state!
Jutul.setup_state_and_parameters
Jutul.setup_storage
Jutul.setup_storage!
Jutul.si_unit
Jutul.si_units
Jutul.simulate
Jutul.simulate
Jutul.simulate!
Jutul.simulator_config
Jutul.solve_adjoint_sensitivities
Jutul.solve_adjoint_sensitivities!
Jutul.solve_numerical_sensitivities
Jutul.solve_timestep!
Jutul.subvariable
Jutul.successful_reports
Jutul.synchronize
Jutul.tpfv_geometry
Jutul.transfer
Jutul.two_point_potential_drop
Jutul.unsafe_reinterpret
Jutul.update_before_step!
Jutul.update_equation!
Jutul.update_equations!
Jutul.update_equations_and_apply_forces!
Jutul.update_linearized_system!
Jutul.update_linearized_system_equation!
Jutul.update_secondary_variable!
Jutul.update_state_dependents!
Jutul.update_values!
Jutul.update_values!
Jutul.value
Jutul.value
Jutul.values_per_entity
Jutul.variable_scale
Jutul.write_reports_to_mat_format
JutulDarcy.component_mass_fluxes!
JutulDarcy.default_limits
JutulDarcy.plot_reservoir
JutulDarcy.plot_reservoir_simulation_result
JutulDarcy.plot_well_results
JutulDarcy.replace_target
JutulDarcy.reservoir_domain
JutulDarcy.reservoir_linsolve
JutulDarcy.reservoir_system
JutulDarcy.setup_case_from_data_file
JutulDarcy.setup_case_from_mrst
JutulDarcy.setup_case_from_parsed_data
JutulDarcy.setup_reservoir_model
JutulDarcy.setup_reservoir_simulator
JutulDarcy.setup_reservoir_state
JutulDarcy.setup_vertical_well
JutulDarcy.setup_well
JutulDarcy.simulate_data_file
JutulDarcy.simulate_mrst_case
JutulDarcy.simulate_reservoir
JutulDarcy.simulate_reservoir_parray
JutulDarcy.update_total_masses!
Jutul.@jutul_secondary