DOCSEARCHbyAlgolia
Submit Docs

JutulDarcy.jl

repository·main·Indexed 41 days ago

https://github.com/sintefmath/jutuldarcy.jl

A high-performance, fully differentiable reservoir simulator written in Julia for Darcy-scale and subsurface flow modeling, including CO2 sequestration, geothermal, and oil/gas. It supports immiscible multi-phase flow, black-oil models, compositional flow, and geothermal systems. Key features include automatic differentiation, MPI support with domain decomposition, and integration with Makie.jl for 3D visualization. Available as a Julia package and via Python bindings.

Tokens
15.3K
Snippets
49
Records
106
Agent score
51%

What's inside JutulDarcy

  1. Overview of JutulDarcy.jl physical systems

    main

    JutulDarcy.jl is a high-performance, fully differentiable porous media simulator. It supports several physical systems:

    • Immiscible multi-phase flow
    • Black-oil models: Supports dissolved vapor (Rs) and vaporized liquid (Rv).
    • Compositional flow: Equation-of-state (EOS) models with up to three phases and any number of components.
    • Geothermal systems

    All solvers support general multisegment wells with mass balance, friction pressure loss, complex well limits, and time-dependent controls.

  2. Overview of supported physical systems in JutulDarcy

    main

    JutulDarcy uses JutulSystem instances to model different types of porous media flow physics. The systems range from simple single-phase flow to complex multi-phase compositional and thermal models. All systems are based on conservation laws for $N$ components in residual form:

    $R = \frac{\partial}{\partial t} M_i + \nabla \cdot \vec{V}_i - Q_i$

    where $M_i$ is the conserved quantity (mass), $\vec{V}_i$ is the velocity, and $Q_i$ represents source terms (direct sources, boundary conditions, or wells).

  3. Understand unit requirements in JutulDarcy

    main

    JutulDarcy requires consistent units throughout the model definition, typically using strict SI units. While the core engine is free from internal conversion factors, you must ensure all inputs are converted to SI before they reach the simulation engine.

    Key implications:

    • Input Files: .DATA or .AFI files are automatically converted to SI when parsed using default settings.
    • Simulation Outputs: Outputs like pressure (Pascals), temperature (Kelvin), and surface rates (SI units per second) may have very large or very small magnitudes compared to field units.
    • Permeability: SI units for permeability are in $m^2$, which are extremely small ($1 ext{ m}^2 ext{ is roughly } 10^{12} ext{ millidarcy}$). Avoid inputting millidarcy values directly without conversion.

  4. GPU support technical details and limitations

    main

    Performance and Hardware

    • Multi-threading: Since the implementation uses assembly on the CPU and pinned memory for transfers, launching Julia with multiple threads can improve performance for non-GPU tasks.
    • Precision: Use float_type = Float32 in linear_solver_arg to utilize lower precision for faster solves.
    • Platform: AMGX is currently limited to Linux and is single-GPU only (does not work with MPI). Windows users should use WSL.

    Experimental Warning

    GPU support is experimental. Successive runs with different AMGX instances may cause crashes during garbage collection.

  5. Align time-stepping and reporting for comparisons

    main

    JutulDarcy uses dynamic time-stepping to ensure it hits requested report steps. Differences in time-step selection between simulators can lead to different results.

    To achieve higher resolution reporting (similar to how Eclipse reports sparse data like well results at higher intervals than the requested reporting interval), set the following option:

    output_substates = true

    output_substates = true

  6. Choose between Simple and Multisegment wells

    main

    JutulDarcy provides two primary abstractions for wells:

    1. Simple wells (SimpleWell): Used for basic well modeling where the wellbore physics are simplified.
    2. Multisegment wells (MultiSegmentWell): Used for more complex modeling involving wellbore hydraulics and segment-based flow. This includes support for:
      • SegmentWellBoreFrictionHB: Wellbore friction modeling.
      • PotentialDropBalanceWell: Wells governed by potential drop balance.
      • MixedWellSegmentFlow: Mixed flow regimes within segments.
      • WellDomain: The domain associated with a multisegment well.

  7. Configure well controls and targets

    main

    Wells in JutulDarcy are managed via controls that dictate how the well behaves (e.g., as an injector or producer) and targets that define the desired operating point.

    Well Controls

    Controls define the mode of operation:

    • InjectorControl: For injecting fluids into the reservoir.
    • ProducerControl: For extracting fluids from the reservoir.
    • DisabledControl: To turn a well off.
    • Use replace_target to update an existing target or default_limits to reset constraints.

    Well Targets

    Targets specify the physical quantity the well control attempts to maintain:

    • Pressure Targets: BottomHolePressureTarget.
    • Rate Targets: SinglePhaseRateTarget, SurfaceLiquidRateTarget, SurfaceOilRateTarget, SurfaceGasRateTarget, SurfaceWaterRateTarget, TotalRateTarget, TotalMassRateTarget, TotalReservoirRateTarget.
    • Voidage Targets: ReservoirVoidageTarget, HistoricalReservoirVoidageTarget.
    • Disabled: DisabledTarget.

  8. How Schur complement handles multi-model systems (porous medium with wells)

    main

    When a model includes both a porous medium (reservoir) and a well system, JutulDarcy uses a Schur complement approach to solve the coupled system efficiently. This avoids the high computational cost of explicitly forming the large coupled matrix.

    The Process:

    1. The system is partitioned into reservoir equations ($J_{rr}$) and well equations ($J_{ww}$).
    2. Instead of forming the full matrix, JutulDarcy uses the action of the Schur complement ($J_{rr} - J_{rw}J_{ww}^{-1}J_{wr}$) as a linear operator from LinearOperators.jl.
    3. The reservoir degrees of freedom are solved first using the existing block preconditioners.
    4. The well degrees of freedom are then recovered directly using the well system's inverse.

    Note on Efficiency: This approach is efficient because $J_{ww}$ is typically small, making its factorization inexpensive to store and reuse during the linear operator application.

  10. Input/Output and Visualization capabilities

    main

    JutulDarcy.jl provides several tools for data handling and visualization:

    • Data Files: Supports reading .DATA files with corner point grids, including non-conformal faults and inactive cells.
    • MRST Integration: Supports unstructured grids and complex cases from the Matlab Reservoir Simulation Toolbox (MRST) via the jutul module.
    • 3D Visualization: 3D visualization of grids and wells is available by loading a Makie.jl backend (requires Julia 1.9 and GLMakie for interactivity).
    • Well Curves: Supports interactive plotting of well curves.

  11. Key architectural features of JutulDarcy.jl

    main

    The simulator is designed for high performance and optimization:

    • Differentiability: Fully differentiable with respect to forces and discretization parameters using automatic differentiation and the adjoint method for sensitivities.
    • Solvers: High-performance assembly and linear solvers, including two-stage CPR BILU(0)-CPR Krylov solvers.
    • Parallelism: MPI support with domain decomposition and BoomerAMG-CPR solver with automatic METIS partitioning.
    • Discretization: Support for consistent discretizations like AvgMPFA and NTPFA.
    • Sparsity: Dynamic sparsity detection.

  12. Understand the relationship between JutulDarcy.jl and Jutul.jl

    main

    JutulDarcy.jl is a high-level package built on top of Jutul.jl. While JutulDarcy.jl provides the specific physics and models for Darcy flow, Jutul.jl handles the underlying computational heavy lifting, including:

    • Meshes: Grid generation and management.
    • Discretizations: Numerical schemes for solving equations on meshes.
    • Solvers: The engines used to solve the resulting systems of equations.

    You can use JutulDarcy.jl without deep knowledge of Jutul.jl, but advanced customization may require referencing the Jutul.jl manual or docstrings.