---
title: "Rpvt Package"
date: "`r Sys.Date()`"
output:
      rmarkdown::html_vignette
bibliography: REFERENCES.bib
csl: apa-6th-edition.csl
vignette: |
  %\VignetteIndexEntry{Rpvt} 
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8} 
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

```


## `Rpvt`

`Rpvt` is a correlation-based PVT (Pressure-Volume-Temperature) package for dry gas, wet gas, black oil, and water samples. It generates PVT properties of hydrocarbons and water samples in a tabular format at a constant temperature from atmospheric pressure up to the pressure of interest. Predictions for gas, oil, and water samples are generated by **`pvt_gas()`**, **`pvt_oil()`**, and **`pvt_water()`** functions, respectively.<br>


## `pvt_gas() arguments`

+ `input_unit`: input unit system for parameters, a character string either 'SI' or 'Field'.
+ `output_unit`: output unit system for properties, a character string either 'SI' or 'Field'.
+ `fluid`: fluid type, a character string either 'dry_gas' or 'wet_gas'.
+ `pvt_model`: PVT model, the character string 'DAK'.
+ `visc_model`: viscosity model, the character string 'Sutton'.
+ `t`: Reservoir temperature, a numeric value either in 'C' or 'F' depending on the 'input_unit'.
+ `p`: Reservoir pressure, a numeric value either in 'kPag' or 'Psig' depending on the 'input_unit'.
+ `gas_spgr`: gas specific gravity (Air = 1.0).
+ `nhc_composition`: a vector of mole fractions for nitrogen, hydrogen sulfide, and carbon dioxide, respectively.
+ `cgr`: condensate to gas ratio, a numeric value in 'm3/m3' or 'STB/MMSCF' depending on the 'input_unit'.
+ `cond_api`: condensate API gravity used for wet gas samples. It must be `NULL` for dry gas mixtures.
+ `warning`: a charater string either 'yes' or 'no'. It shows warning messages for input parameters outside the range of correlations.


## `pvt_oil() arguments`

+ `input_unit`: input_unit input unit system for parameters, a character string either 'SI' or 'Field'.
+ `output_unit`: output_unit output unit system for properties, a character string either 'SI' or 'Field'.
+ `fluid`: fluid type, the character string 'black_oil'.
+ `pvt_model`: PVT model, a character string. 'Standing', 'Vasquez_Beggs', 'Farshad_Petrosky', 'Al_Marhoun', and 'Glaso' models are currently available.
+ `visc_model`: viscosity model, a character string. 'Beggs_Robinson', and 'Al_Marhoun' models are currently available.
+ `t`: Reservoir temperature, a numeric value either in 'C' or 'F' depending on the 'input_unit'.
+ `p`: Reservoir pressure, a numeric value either in 'kPag' or 'Psig' depending on the 'input_unit'.
+ `oil_api`: API gravity of oil.
+ `gas_spgr`: gas specific gravity (Air = 1.0).
+ `nhc_composition`: a vector of mole fractions for nitrogen, hydrogen sulfide, and carbon dioxide, respectively.
+ `rsi`: initial solution gas oil ratio in  'm3/m3' or 'SCF/STB' depending on the 'input_unit'. It is either NULL or a numeric value. If 'rsi' is NULL, then a numeric value must be assigned to 'pb'.
+ `pb`: bubble point pressure, a numeric value either in 'kPag' or 'Psig' depending on the 'input_unit'. it is either NULL or a numeric value. If 'pb' is NULL, then a numeric value must be assigned to 'rsi'.
+ `warning`: a charater string either 'yes' or 'no'. It shows warning messages for input parameters outside the range of correlations.


## `pvt_water() arguments`

+ `input_unit`: input_unit input unit system for parameters, a character string either 'SI' or 'Field'.
+ `output_unit`: output unit system for properties, a character string either 'SI' or 'Field'.
+ `fluid`: fluid type, the character string 'water'.
+ `pvt_model`: PVT model, a character string. 'Spivey', 'Meehan', and 'McCain' models are currently available.
+ `visc_model`: viscosity model, a character string. 'Spivey', 'Meehan', and 'McCain' models are currently available.
+ `t`: Reservoir temperature, a numeric value either in 'C' or 'F' depending on the 'input_unit'.
+ `p`: Reservoir pressure, a numeric value either in 'kPag' or 'Psig' depending on the 'input_unit'.
+ `gas_saturated`: a charater string either 'yes' or 'no'.
+ `salinity`: water salinity in weight percent TDS.
+ `warning`: a charater string either 'yes' or 'no'. It shows warning messages for input parameters outside the range of correlations.


## `Units` for input parameters
The `input_unit` is either `SI` or `Field`. Depending on the `input_unit` system, the following units are used for the input parameters:

+ `t`: "F" in "Field" or "C" in "SI".
+ `p`: "Psig" in "Field" or "kPag" in "SI".
+ `cgr`: "STB/MMSCF" in "Field" or "m3/m3" in "SI".
+ `rsi`: "SCF/STB" in "Field" or "m3/m3" in "SI".
+ `pb`: "Psig" in "Field" or "kPag" in "SI".

## `Gas Correlations`

+ `pvt_model`: "DAK" correlation (Dranchuk and Abou-Kassem) [@Sutton2007].
+ `visc_model`: "Sutton" correlation [@Sutton2007].

## `Oil Correlations`

+ `pvt_model`: "Standing", "Vasquez_Beggs", "Farshad_Petrosky", "Al_Marhoun", or "Glaso" correlations [@Standing1947; @Vasquez1980; @PetroskyJr.1998; @Al-Marhoun1988; @Glaso1980]. "Spivey" correlation is used for estimating the oil compressibility above the bubble point [@Spivey2007].
+ `visc_model`: "Beggs_Robinson", or "Al_Marhoun" correlations [ @Beggs1975; @Al-Marhoun2004].

## `Water Correlations`

+ `pvt_model`: "Spivey", "McCain" or "Meehan" correlations [@McCainJr.1991; @Meehan1980a; @Meehan1980b; @Spivey2004; @McCainJr.2011].
+ `visc_model`: "Spivey", "McCain" or "Meehan" correlations [@McCainJr.1991; @Meehan1980a; @Meehan1980b; @Spivey2004; @McCainJr.2011].


## `Installation`

The `Rpvt` can be installed from [CRAN](https://CRAN.R-project.org) with:


```{r, eval = FALSE, warning = FALSE}
install.packages("Rpvt")
```


## `Gas PVT Examples`

#### Example 1:

```{r, fig.width = 6, fig.height= 8, fig.align = "center", warning = TRUE}
library(Rpvt)
library(ggplot2)
library(magrittr)
library(ggpubr)

pvt_gas_1 <- pvt_gas(input_unit = "Field", output_unit = "Field", 
fluid = "dry_gas", pvt_model = "DAK", visc_model = "Sutton", 
t = 400, p = 30000, gas_spgr = 0.65, nhc_composition = c(0.03,0.012,0.018),
cgr = 0, cond_api = NULL, warning = "yes")

attributes(pvt_gas_1)

pvt_gas_1 <- as.data.frame(pvt_gas_1)

head(pvt_gas_1,10)

colnames(pvt_gas_1) <- c("T(F)", "P(Psig)", "Z-FACTOR", "Bg(rb/scf)", 
                         "Density(lb/ft3)", "Cg(1/Psi)", "MUg(cp)", 
                         "m(p)(Psia^2/cp)")
Z_plot <- pvt_gas_1 %>% ggplot(aes(x = `P(Psig)`, y = `Z-FACTOR`)) +
  geom_point(color = "blue") +
  xlab(label = "P (Psig)") +
  ylab(label = "Z-Factor") +
  theme_bw()
Density_plot <- pvt_gas_1 %>% ggplot(aes(x = `P(Psig)`, y = `Density(lb/ft3)`)) +
  geom_point(color = "blue") +
  xlab(label = "P (Psig)") +
  ylab(label = "Density (lb/ft3)") +
  theme_bw()
Bg_plot <- pvt_gas_1 %>% ggplot(aes(x = `P(Psig)`, y = `Bg(rb/scf)`)) +
  geom_point(color = "blue") +
  scale_y_log10() +
  xlab(label = "P (Psig)") +
  ylab(label = "Gas FVF (rb/scf)") +
  theme_bw()
Cg_plot <- pvt_gas_1 %>% ggplot(aes(x = `P(Psig)`, y = `Cg(1/Psi)`)) +
  geom_point(color = "blue") +
  scale_y_log10() +
  xlab(label = "P (Psig)") +
  ylab(label = "Compressibility (1/Psi)") +
  theme_bw()
MUg_plot <- pvt_gas_1 %>% ggplot(aes(x = `P(Psig)`, y = `MUg(cp)`)) +
  geom_point(color = "blue") +
  xlab(label = "P (Psig)") +
  ylab(label = "Viscosity (cp)") +
  theme_bw()
mp_plot <- pvt_gas_1 %>% ggplot(aes(x = `P(Psig)`, y = `m(p)(Psia^2/cp)`)) +
  geom_point(color = "blue") +
  xlab(label = "P (Psig)") +
  ylab(label = "Pseudopressure (Psia^2/cp)") +
  theme_bw()

gas_pvt_plots <- ggarrange(Z_plot, Density_plot, Bg_plot, Cg_plot, MUg_plot, mp_plot,
                      ncol = 2, nrow = 3, align = "v")


gas_pvt_plots 
```

#### Example 2:

```{r}

pvt_gas_2 <- pvt_gas(input_unit = "Field", output_unit = "SI", 
fluid = "wet_gas", pvt_model = "DAK", visc_model = "Sutton", 
t = 300, p = 5000, gas_spgr = 0.75, nhc_composition = c(0.05,0.01,0.04),
cgr = 5, cond_api = 42.3, warning = "no")

tail(as.data.frame(pvt_gas_2), 10)

```


## `Oil PVT Examples`

#### Example 1:

```{r, fig.width = 6, fig.height= 12, fig.align = "center", warning = TRUE}
library(Rpvt)
library(ggplot2)
library(magrittr)
library(ggpubr)

pvt_oil_1 <- pvt_oil(input_unit = "Field", output_unit = "Field", 
                                   fluid = "black_oil", pvt_model = "Standing",
                                   visc_model = "Beggs_Robinson", t = 200, p = 3000, 
                                   oil_api = 35, gas_spgr = 0.8,
                                   nhc_composition = c(0.05,0.02,0.04), 
                                   rsi = 650, pb = NULL, warning = "yes")

attributes(pvt_oil_1)

pvt_oil_1 <- as.data.frame(pvt_oil_1)

tail(pvt_oil_1, 10) 

Rs_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Rso_(scf/stb)`)) +
  geom_point(color = "blue", size = 2) +
  xlab(label = "P (Psig)") +
  ylab(label = "Rs (SCF/STB)") +
  theme_bw()
Bo_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Bo_(rb/stb)`)) +
  geom_point(color = "blue", size = 2) +
  xlab(label = "P (Psig)") +
  ylab(label = "Oil FVF (rb/STB)") +
  theme_bw()
RHOo_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Oil_Density_(lb/ft3)`)) +
  geom_point(color = "blue", size = 2) +
  xlab(label = "P (Psig)") +
  ylab(label = "Oil Density (lb/ft3)") +
  theme_bw()
Co_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Co_(1/Psia)`)) +
  geom_point(color = "blue", size = 2) +
  scale_y_log10() +
  xlab(label = "P (Psig)") +
  ylab(label = "Oil Compressibility (1/Psi)") +
  theme_bw()
MUo_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Oil_Viscosity_(cp)`)) +
  geom_point(color = "blue", size = 2) +
  scale_y_log10() +
  xlab(label = "P (Psig)") +
  ylab(label = "Oil Viscosity (cp)") +
  theme_bw()
Bg_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Bg_(rb/scf)`)) +
  geom_point(color = "blue", size = 2) +
  scale_y_log10() +
  xlab(label = "P (Psig)") +
  ylab(label = "Gas FVF (rb/SCF)") +
  theme_bw()
Cg_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Cg_(1/Psia)`)) +
  geom_point(color = "blue", size = 2) +
  scale_y_log10() +
  xlab(label = "P (Psig)") +
  ylab(label = "Gas Compressibility (1/Psi)") +
  theme_bw()
MUg_plot <- pvt_oil_1 %>% ggplot(aes(x = `P_(Psig)`, y = `Gas_Viscosity_(cp)`)) +
  geom_point(color = "blue", size = 2) +
  xlab(label = "P (Psig)") +
  ylab(label = "Gas Viscosity (cp)") +
  theme_bw()
oil_pvt_plots <- ggarrange(Rs_plot, RHOo_plot, Bo_plot, Bg_plot, Co_plot, Cg_plot, MUo_plot, MUg_plot,
                      ncol = 2, nrow = 4, align = "v")

oil_pvt_plots
```


#### Example 2:

```{r}

pvt_oil_2 <- pvt_oil(input_unit = "SI", output_unit = "SI", fluid = "black_oil",
                     pvt_model = "Vasquez_Beggs", visc_model = "Al_Marhoun", 
                     t = 100, p = 20000, oil_api = 40, gas_spgr = 0.75, 
                     nhc_composition = c(0.05,0.02,0.04), 
                     rsi = NULL, pb = 13000, warning = "yes")

head(as.data.frame(pvt_oil_2), 10)

```


#### Example 3:


```{r}

pvt_oil_3 <- pvt_oil(input_unit = "Field", output_unit = "SI", fluid = "black_oil",
                     pvt_model = "Farshad_Petrosky", visc_model = "Al_Marhoun", 
                     t = 260, p = 4000, oil_api = 38, gas_spgr = 0.68, 
                     nhc_composition = c(0.03,0.07,0.08), 
                     rsi = NULL, pb = 2500, warning = "yes")

head(as.data.frame(pvt_oil_3), 10)

```



## `Water PVT Examples`

#### Example 1:

```{r, fig.width = 6, fig.height= 8, fig.align = "center", warning = TRUE}
library(Rpvt)
library(ggplot2)
library(magrittr)
library(ggpubr)

pvt_water_1 <- as.data.frame(pvt_water(input_unit = "SI", output_unit = "SI", 
fluid = "water", pvt_model = "Spivey", visc_model = "Spivey", t = 150, p = 200000, 
salinity = 5, gas_saturated = "yes", warning = "yes"))

head(pvt_water_1,10)

colnames(pvt_water_1) <- c("T(C)", "P(kPag)", "Rsw(rm3/sm3)", "Bw(rm3/sm3)", 
                         "Density(kg/m3)", "Cw(1/kPa)", "MUw(mPa.s)")
Solubility_plot <- pvt_water_1 %>% ggplot(aes(x = `P(kPag)`, y = `Rsw(rm3/sm3)`)) +
  geom_point(color = "blue") +
  xlab(label = "P (kPag)") +
  ylab(label = "Gas solubility in water (rm3/sm3)") +
  theme_bw()
Density_plot <- pvt_water_1 %>% ggplot(aes(x = `P(kPag)`, y = `Density(kg/m3)`)) +
  geom_point(color = "blue") +
  xlab(label = "P (kPag)") +
  ylab(label = "Density (kg/m3)") +
  theme_bw()
Bw_plot <- pvt_water_1 %>% ggplot(aes(x = `P(kPag)`, y = `Bw(rm3/sm3)`)) +
  geom_point(color = "blue") +
  scale_y_log10() +
  xlab(label = "P (kPag)") +
  ylab(label = "Water FVF (rm3/sm3)") +
  theme_bw()
Cw_plot <- pvt_water_1 %>% ggplot(aes(x = `P(kPag)`, y = `Cw(1/kPa)`)) +
  geom_point(color = "blue") +
  scale_y_log10() +
  xlab(label = "P (kPag)") +
  ylab(label = "Compressibility (1/kPa)") +
  theme_bw()
MUw_plot <- pvt_water_1 %>% ggplot(aes(x = `P(kPag)`, y = `MUw(mPa.s)`)) +
  geom_point(color = "blue") +
  xlab(label = "P (kPag)") +
  ylab(label = "Viscosity (mPa.s)") +
  theme_bw()
water_pvt_plots <- ggarrange(Solubility_plot, Density_plot, Bw_plot, Cw_plot, MUw_plot,
                      ncol = 2, nrow = 3, align = "v")

water_pvt_plots 
```

#### Example 2:

```{r}

pvt_water_2 <- as.data.frame(pvt_water(input_unit = "Field", output_unit = "SI", 
fluid = "water", pvt_model = "McCain", visc_model = "McCain", t = 200, p = 4000, 
salinity = 15, gas_saturated = "yes", warning = "yes"))

head(pvt_water_2, 10)

```

#### Example 3:

```{r}

pvt_water_3 <- pvt_water(input_unit = "Field", output_unit = "Field",
fluid = "water", pvt_model = "Meehan", visc_model = "Meehan",
t = 300, p = 3000,  salinity = 10, gas_saturated = "no", warning = "yes")

tail(as.data.frame(pvt_water_3), 10)

```


## `References`

