README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# rEcl

The goal of `rEcl` is to serve as an R wrapper of the class `EclBinaryParser`, written in Python by Konstantin Sermyagin, a reservoir engineer. The class converts the reservoir simulation output files generated by Eclipse from binary to dataframes.

## Installation
For the moment, `rEcl` is only available through Github. 

Once is completed it will be submitted to CRAN. You can install it in the meantime by two methods:

* cloning or downloading the package from Github
* install it using `devtools::install_github("f0nzie/rEcl", ref = "the_branch")`, where the branch could be `master` or `develop`, depending how newer or bleeding edge you like it.


## Requirements

* R 3.5.3
* Rtools 3.5
* RStudio 1.2+. _I used RStudio preview 1.2.1327 for the development of the package._
* Python Anaconda3-2018.12-Windows-x86_64
* Conda environment 3.6 with pandas and numpy installed. _I called this environment_ `pyres`


## Files used for testing
For testing `rEcl` and `EclBinaryParser` I used the output binary files from the reservoir simulation of the Volve field.

```
VOLVE_2016.INIT
VOLVE_2016.RSSPEC
VOLVE_2016.SMSPEC
VOLVE_2016.UNSMRY
```

You can find a copy of these files in this repository under [rEcl/inst/python/volve](https://github.com/f0nzie/rEcl/tree/master/inst/python/volve), but the `rEcl` package will not install them. You will have to copy these files manually. In the future, I plan to download the files directly from Zenodo or Google drive; mainly, because these files are too big for an R package.

## Functions for the class EclBinaryParser

* `get_dimens`
* `is_dual`
* `get_actnum`
* `get_seqnum_dates`
* `read_prop_array`
* `read_prop_time`
* `read_vectors`


### New functions

* `get_vectors_shape`: get the shape or dimensions of the vectors dataframe
* `get_vector_names`: get the names of all the vectors
* `get_vector_column`: get the values for a vector-column



## Examples

### Example reservoir model SPE6

We start by reading the file `SPE6_FRAC.UNSMRY`. This file , because is relatively small, we can include it with the package. We willread it from the package installation folder.

```{r}
library(reticulate)

reticulate::use_condaenv("pyres", required = TRUE)
reticulate::py_config()
```

```{r}
library(rEcl)

ecl_folder <- system.file("rawdata", package = "rEcl")
ecl_folder
unsmry_file <- file.path(ecl_folder, "spe6", "SPE6_FRAC.UNSMRY")
file.exists(unsmry_file)
```

We connect to Python and load the class `EclBinaryParser` which resides in the Python package called `restools`. You can take a look at `restools` under the R installation folder in your lcoal disk.

Once we connect and load the Python package, we create an instance of the class `EclBinaryParser` providing the parse object `py` and the full name of the Eclipse binary file.

```{r}
py <- restools_connect()
parser <- EclBinaryParser(py, unsmry_file)
```

First basic task is finding the dimensions of the reservoir model. We do that with `get_dimensions`.

```{r}
get_dimensions(parser)
```

This is a heavier operation; reading the vectors.

```{r}
vectors <- read_vectors(parser)
```

Get the shape or dimensions of the vector dataframe.

```{r}
get_vectors_shape(parser)
```

We get the names of the vectors we specified in our input file.

```{r}
get_vector_names(parser)
```

We now want a dataframe corresponding to a specific vector-column with `get_vector_column`:

```{r}
get_vector_column(parser, "FOPR")
```

Finally, because the function `get_vector_column` is vectorized, we can get a dataframe of multiple columns.

```{r}
# get several vectors at once
df_vars <- get_vector_column(parser, c("FPR", "FGOR", "FOPR"))
df_vars
```


## Example reservoir model PUNQ-S3
PUNQ-S3 is a synthetic reservoir model that is used for testing and calibrating reservoir simulators. These are the files available with the package:

```
PUNQS3.INIT
PUNQS3.INSPEC
PUNQS3.RSSPEC
PUNQS3.SMSPEC
PUNQS3.UNRST
PUNQS3.UNSMR
```

You may list the files with:

`list.files(system.file("python", "volve", package = "rEcl"))`

```{r}
library(reticulate)

reticulate::use_condaenv("pyres", required = TRUE)
reticulate::py_config()
```

```{r}
library(rEcl)

ecl_folder <- system.file("rawdata", package = "rEcl")
unsmry_file <- file.path(ecl_folder, "PUNQS3", "PUNQS3.UNSMRY")
file.exists(unsmry_file)
```

```{r}
# connect to Python and start a class instance
py <- restools_connect()
parser <- EclBinaryParser(py, unsmry_file)

# dimensions of the reservoir model
get_dimensions(parser)
```



```{r}
# reading the Eclipse vectors. this may take few seconds id the reservoir is too complex
vectors <- read_vectors(parser)

# Get the shape or dimensions of the vector dataframe.
get_vectors_shape(parser)
```

```{r}
# We get the names of the vectors we specified in our input file.
get_vector_names(parser)
```

```{r}
# dataframe corresponding to a specific vector-column
get_vector_column(parser, "FOPR")
```

```{r}
# get a dataframe of multiple columns
# vectorized function to get several vectors at once
df_vars <- get_vector_column(parser, c("YEARS", "FGOR", "FOPR", "FWCT"))
df_vars
```

Eclipse vectors that are different in nature, such as well (start with __W__) variables, will get a different size than field variables (start with __F__):

```{r}
# read a well variable
tibble::as_tibble(get_vector_column(parser, "WBHP"))
```