More doc updates

README.md

@@ -6,16 +6,28 @@
 [![Jutul Darcy logo](docs/src/assets/logo_wide.png)](https://sintefmath.github.io/JutulDarcy.jl/dev/)
 
 # Reservoir simulation in Julia
-JutulDarcy.jl: Darcy-scale and subsurface flow (CO2 sequestration, gas/H2 storage, oil/gas fields) using [Jutul.jl](https://github.com/sintefmath/Jutul.jl) developed by the [Computational Geosciences group](https://www.sintef.no/en/digital/departments-new/applied-mathematics/computational-geoscience/) at [SINTEF Digital](https://www.sintef.no/en/digital/).
+JutulDarcy.jl: Darcy-scale and subsurface flow (CO2 sequestration, gas/H2 storage, oil/gas fields) using [Jutul.jl](https://github.com/sintefmath/Jutul.jl) developed by the [Applied Computational Science group](https://www.sintef.no/en/digital/departments-new/applied-mathematics/applied-computational-sciences/) at [SINTEF Digital](https://www.sintef.no/en/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.
-- Equation-of-state compositional, immiscible and black oil flow is supported and validated against existing simulators
-- Unstructured grids and complex cases input from [the Matlab Reservoir Simulation Toolbox (MRST)](https://www.mrst.no) using the `jutul` module.
-- Support for general multisegment wells with rigorous mass balance, complex well limits and time-dependent controls
+- 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)](https://www.mrst.no) 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](https://docs.makie.org/stable/) backend (requires Julia 1.9, `GLMakie` for interactivity)
 - Interactive plotting of well curves
 
@@ -28,7 +40,7 @@ The compositional simulator has been matched against commercial offerings, AD-GP
 | SPE9      | 9000  | 35           | block-ILU(0)     | 3.41     |
 | Egg       | 18553 | 123          | CPR-block-ILU(0) | 8.60     |
 
-Simulated with `julia -O2`, no threads.
+Simulated with default `julia`, no threads. Runtime with single-threaded HYPRE on the full [SPE10 model 2 model](https://www.spe.org/web/csp/datasets/set02.htm) 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](https://link.springer.com/article/10.1007/s10596-020-10003-4).
 
 ## 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:
@@ -41,7 +53,7 @@ Jutul builds upon many of the excellent packages in the Julia ecosystem. Here ar
 - [PartitionedArrays.jl](https://github.com/fverdugo/PartitionedArrays.jl) for MPI assembly and linear solve
 - [Tullio.jl](https://github.com/mcabbott/Tullio.jl) for automatically optimized loops and [Polyester.jl](https://github.com/JuliaSIMD/Polyester.jl) for lightweight threads
 - [TimerOutputs.jl](https://github.com/KristofferC/TimerOutputs.jl) and [ProgressMeter.jl](https://github.com/timholy/ProgressMeter.jl) gives nice output to terminal 
-- [Makie.jl](https://makie.juliaplots.org/) is used for the visualization features found in [JutulViz.jl](https://github.com/sintefmath/JutulViz.jl)
+- [Makie.jl](https://makie.juliaplots.org/) is used for the visualization features
 - [MultiComponentFlash.jl](https://github.com/moyner/MultiComponentFlash.jl) provides many of the compositional features
 
 ...and many more, both directly in the Project.toml file and indirectly!
@@ -57,6 +69,6 @@ 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](https://sintefmath.github.io/JutulDarcy.jl/dev/) is still work in progress, but contains a fair bit of useful information. In addition, see the [examples](examples/) folder for more information. Some functionality is also demonstrated in the [tests](https://github.com/sintefmath/JutulDarcy.jl/tree/main/test). There are also examples in [JutulExamples](https://github.com/sintefmath/JutulExamples.jl) that may occasionally be a bit out of date.
+The [documentation](https://sintefmath.github.io/JutulDarcy.jl/dev/) is still work in progress, but contains a fair bit of useful information. In addition, see the [examples](examples/) folder for more information. Some functionality is also demonstrated in the [tests](https://github.com/sintefmath/JutulDarcy.jl/tree/main/test).
 
 *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.*

docs/make.jl

@@ -4,7 +4,8 @@ using Literate
 using Documenter
 
 function build_jutul_darcy_docs(build_format = nothing; build_examples = true)
-    DocMeta.setdocmeta!(JutulDarcy, :DocTestSetup, :(using JutulDarcy; using Jutul); recursive=true)
+    DocMeta.setdocmeta!(JutulDarcy, :DocTestSetup, :(using JutulDarcy); recursive=true)
+
     ## Literate pass
     # Base directory
     jutul_dir = joinpath(dirname(pathof(JutulDarcy)), "..")
@@ -45,7 +46,7 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true)
         )
     end
     makedocs(;
-        modules=[JutulDarcy, Jutul],
+        modules=[JutulDarcy],
         authors="Olav Møyner <[email protected]> and contributors",
         repo="https://github.com/sintefmath/JutulDarcy.jl/blob/{commit}{path}#{line}",
         sitename="JutulDarcy.jl",

docs/src/index.md

@@ -22,5 +22,8 @@ Documentation for [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl).
 
 JutulDarcy builds upon the general features found in [Jutul.jl](https://github.com/sintefmath/Jutul.jl). You may also find it useful to look at the [Jutul.jl documentation](https://sintefmath.github.io/Jutul.jl/dev/).
 
+## Reading input files
+It is also possible to read cases that have been set up in MRST (see [setup_case_from_mrst](@ref) and [simulate_mrst_case](@ref)) or from .DATA files (see [parse_data_file](@ref) and [simulate_data_file](@ref))
+
 ```@index
 ```

docs/src/internals.md

@@ -1,19 +1,3 @@
-```@docs
-simulator_config
-simulate!
-simulate
-JutulSystem
-JutulMesh
-JutulDomain
-VectorVariables
-MultiModel
-SimulationModel
-Simulator
-setup_parameters
-setup_state
-setup_forces
-```
-
 ```@autodocs
 Modules = [JutulDarcy]
 ```

docs/src/usage/solution.md

@@ -124,7 +124,16 @@ Once that system is solved for ``\mathbf{x}_r``, we can recover the well degrees
 
 !!! note "Efficiency of Schur complement"
     Explicitly forming the matrix ``J_{rr} - J_{rw}J_{ww}^{-1}J_{wr}`` will generally lead to a lot of fill-in in the linear system. JutulDarcy instead uses the action of ``J_{rr} - J_{rw}J_{ww}^{-1}J_{wr}`` as a linear operator from [LinearOperators.jl](https://github.com/JuliaSmoothOptimizers/LinearOperators.jl). This means that we must apply the inverse of the well system every time we need to compute the residual or action of the system matrix, but fortunately performing the action of the Schur complement is inexpensive as long as ``J_{ww}`` is small and the factorization can be stored. 
-### Parallel support
+
+## References
+[Wallis, J.R. "Incomplete Gaussian Elimination as a Preconditioning for Generalized Conjugate Gradient Acceleration." Paper presented at the SPE Reservoir Simulation Symposium, San Francisco, California, November 1983](https://doi.org/10.2118/12265-MS)
+
+[Cao, H., Tchelepi, H. A., Wallis, J., and H. Yardumian. "Parallel Scalable Unstructured CPR-Type Linear Solver for Reservoir Simulation." Paper presented at the SPE Annual Technical Conference and Exhibition, Dallas, Texas, October 2005](https://doi.org/10.2118/96809-MS)
+# Parallel simulations
+
+JutulDarcy can use threads by default, but advanced options can improve performance significantly for larger models.
+
+## Overview of parallel support
 There are two main ways of exploiting multiple cores in Jutul/JutulDarcy: Threads are automatically used for assembly and can be used for parts of the linear solve. If you require the best performance, you have to go to MPI where the linear solvers can use a parallel [BoomerAMG preconditioner](https://hypre.readthedocs.io/en/latest/solvers-boomeramg.html) via [HYPRE.jl](https://github.com/fredrikekre/HYPRE.jl).
 #### Shared memory
 An experimental thread-parallel backend for matrices and linear algebra can be enabled by setting `backend=:csr` in the call to [`setup_reservoir_model`](@ref). This backend provides additional features such as a parallel zero-overlap ILU(0) implementation and parallel apply for AMG, but these features are still work in progress.
@@ -136,12 +145,8 @@ It is possible to run cases using MPI. You will have to set up an environment wi
 Write your script as usual, but in your call to `setup_reservoir_simulator`, pass the optional argument `mode = :mpi`. You must then run the file using `mpiexec`. 
 
 !!! note
-   You should be familiar with the MPI programming model to use this feature. See [MPI.jl](https://juliaparallel.org/MPI.jl/stable/) and [MPIClusterManagers.jl](https://github.com/JuliaParallel/MPIClusterManagers.jl) for more details, and how MPI is handled in Julia specifically.
+    You should be familiar with the MPI programming model to use this feature. See [MPI.jl](https://juliaparallel.org/MPI.jl/stable/) and [MPIClusterManagers.jl](https://github.com/JuliaParallel/MPIClusterManagers.jl) for more details, and how MPI is handled in Julia specifically.
 
 !!! note
-   MPI consolidates results by writing files to disk. Unless you have a plan to work with the distributed states in-memory returned by the `simulate!` call, it is best to specify a `output_path` optional argument to `setup_reservoir_simulator`. After the simulation, that folder will contain output just as if you had run the case in serial.
-
-## References
-[Wallis, J.R. "Incomplete Gaussian Elimination as a Preconditioning for Generalized Conjugate Gradient Acceleration." Paper presented at the SPE Reservoir Simulation Symposium, San Francisco, California, November 1983](https://doi.org/10.2118/12265-MS)
+    MPI consolidates results by writing files to disk. Unless you have a plan to work with the distributed states in-memory returned by the `simulate!` call, it is best to specify a `output_path` optional argument to `setup_reservoir_simulator`. After the simulation, that folder will contain output just as if you had run the case in serial.
 
-[Cao, H., Tchelepi, H. A., Wallis, J., and H. Yardumian. "Parallel Scalable Unstructured CPR-Type Linear Solver for Reservoir Simulation." Paper presented at the SPE Annual Technical Conference and Exhibition, Dallas, Texas, October 2005](https://doi.org/10.2118/96809-MS)

examples/compositional_5components.jl

@@ -3,7 +3,6 @@
 # different components. Other than that, the example is similar to the others
 # that include wells and is therefore not commented in great detail.
 using MultiComponentFlash
-Darcy, bar, kg, meter, Kelvin, day = si_units(:darcy, :bar, :kilogram, :meter, :Kelvin, :day)
 
 n2_ch4 = MolecularProperty(0.0161594, 4.58e6, 189.515, 9.9701e-05, 0.00854)
 co2 = MolecularProperty(0.04401, 7.3866e6, 304.200, 9.2634e-05, 0.228)
@@ -21,6 +20,7 @@ mixture = MultiComponentMixture([n2_ch4, co2, c2_5, c6_13, c14_24], A_ij = bic,
 eos = GenericCubicEOS(mixture, PengRobinson())
 
 using Jutul, JutulDarcy, CairoMakie
+Darcy, bar, kg, meter, Kelvin, day = si_units(:darcy, :bar, :kilogram, :meter, :Kelvin, :day)
 nx = ny = 20
 nz = 2