Commit 4da6c31c authored by Denis Anikiev's avatar Denis Anikiev
Browse files

Updates for publication

parent c1e87123
*.ipynb_checkpoints
**/.ipynb_checkpoints
results/
\ No newline at end of file
# Changelog
All notable changes to this project will be documented in this file.
## [1.0] - 2022-04-05
### Added
- LICENCES folder
- License file for data
- LICENSE.md
### Changed
- name and contents of the main `.ipynb` file
- README contents
- data files are in data folder now
- LICENSE moved to LICENSES/PY4HIP_LICENSE
## [0.1] - 2022-02-21
### Added
- This changelog
......
# License
Jupyter notebook [**Py4HIP**](./Py4HIP.ipynb) is licensed under the [EUROPEAN UNION PUBLIC LICENCE v. 1.2](https://joinup.ec.europa.eu/collection/eupl/introduction-eupl-licence) - see the [PY4HIP_LICENSE](./LICENSES/PY4HIP_LICENSE) file for details.
Test data files in [data](./data/) are licensed under the [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/) - see the [DATA_LICENSE](./LICENSES/DATA_LICENSE) file for details.
......@@ -5,10 +5,38 @@
[TOC]
## Description
**Py4HIP** is implemented as a self-explanatory [Jupyter notebook]()
**Py4HIP** is implemented as a self-explanatory [Jupyter notebook](https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html) [Py4HIP.ipynb](./Py4HIP.ipynb).
## Installation
To get the tool, clone the git repository:
## Getting started
### Requirements
**Py4HIP** requires [Python](https://www.python.org/) $\ge$ 3.5, [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/) and uses the following packages:
- [ipywidgets](https://github.com/jupyter-widgets/ipywidgets)
- [numpy](https://github.com/numpy/numpy)
- [pandas](https://github.com/pandas-dev/pandas)
- [scipy](https://github.com/scipy/scipy)
- [matplotlib](https://github.com/matplotlib/matplotlib)
- [openpyxl](https://foss.heptapod.net/openpyxl/openpyxl)
- [pathlib](https://docs.python.org/3/library/pathlib.html)
### Installation
The following instructions explain how to istall the required packages with with [`conda`](https://docs.conda.io/en/latest/).
We recommend to use [miniforge](https://github.com/conda-forge/miniforge) prompt
To install the required packages open conda prompt and run:
```
conda install -y ipywidgets numpy pandas scipy matplotlib openpyxl pathlib
```
**Note:** you may want to use a specific [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
Install the JupyterLab:
```
conda install -y jupyterlab
```
Get the tool by cloning the git repository using [Git](https://git-scm.com/):
```bash
git clone git@git.gfz-potsdam.de:basin-modelling/python/py4hip.git
```
......@@ -16,21 +44,48 @@ or
```bash
git clone https://git.gfz-potsdam.de/basin-modelling/python/py4hip.git
```
Alternatively, load the package as [zip file](https://git.gfz-potsdam.de/basin-modelling/python/py4hip/-/archive/main/py4hip-main.zip).
### How to run
1. Open conda prompt and start JupyterLab using:
```
jupyter lab
```
You may access JupyterLab by opening the notebook server’s URL in the browser, usually `http://localhost:8888/lab` wihch you can find in the output, e.g.
```
To access the server, open this file in a browser:
<link>
Or copy and paste one of these URLs:
<link>
or <link>
```
It often necessary to insert the token generated after server has started.
You can find this in the command output after `token=`, e.g.:
```
http://localhost:8888/lab?token=73e08328facee92d67a8dd2b587b6fa7cb8a3e3323d653f8
```
2. In the JupyterLab interface open [Py4HIP.ipynb](./Py4HIP.ipynb)
3. Read the instructions and run
## License
This project is licensed under the EUROPEAN UNION PUBLIC LICENCE v. 1.2 - see the [LICENSE](../LICENSE) file for details.
**Py4HIP** is licensed under the [EUROPEAN UNION PUBLIC LICENCE (EUPL) v. 1.2](https://joinup.ec.europa.eu/collection/eupl/introduction-eupl-licence).
See [LICENSE.md](./LICENSE.md) for details.
## Citation
Please cite the software as follows:\
*Bott, J., Benoit, L., Koltzer, N., Anikiev, D. (2022): Py4HIP: Python tool for Heat-In-Place calculations. GFZ German Research Centre for Geosciences. doi:...*
Please cite **Py4HIP** as follows:\
*Bott, J., Benoit, L., Koltzer, N., Anikiev, D. (2022): Py4HIP: Python tool for Heat-In-Place calculations. ... [doi]())*
## Authors and contributions
See also the list of [authors](../AUTHORS.md) who participated in this project.
If you what to contribute to this project please follow [contributing guidelines](../CONTRIBUTING.md).
If you what to contribute to this project please follow the [contributing guidelines](../CONTRIBUTING.md).
## Acknowledgments
Thank you to all colleagues who supported the project by providing test data.
We are grateful to all colleagues who supported the project.
## Contact
[Judith Bott](@sippel): judith.bott@gfz-potsdam.de
%% Cell type:markdown id: tags:
# Py4HIP: Python tool for Heat In Place calculations
**Py4HIP** is a **Py**thon tool **for** **H**eat **I**n **P**lace calculations.
This tool was created to perform **Heat In Place (HIP)** calculations for your region of choice.
Copyright (Bott, Benoit, Koltzer, Anikiev, 2022). Licensed under the EUPL-1.2 or later.
%% Cell type:markdown id: tags:
Heat In Place can be used as a substantial tool to assess the geothermal potential of a selected area and a chosen geological unit within this area. The so called "Heat-In-Place"-Method is well known and still applied (<a>[Nathenson, 1975](#beispiele)</a>;<a>[Muffler and Cataldi, 1978](#beispiele)</a>;<a>[Garg and Combs, 2015](#beispiele)</a>). The **Py4HIP** calculation is based on a volumetric quantification of contained energy after (<a>[Muffler and Cataldi, 1978](#beispiele)</a>) where variable thickness, mean temperature, porosity, density, and specific heat capacity form the main parameters.
$$ H = V ((1 - \phi) \rho_{m} c_{p,m} + \phi \rho_{brine} c_{p, brine}) (T_r - T_{ref}) $$
The reservoir temperature $T_r$ is derived from the point of the mean depth $Z_{mean}$ of the respective model unit (<a>[van Wees et al., 2012](#beispiele)</a>).
$$ Z_{mean, XY} = Z_{min, XY} - \frac{M_{XY}}{2}$$
The specific heat capacity $c_{p,m}$ (of solids) is due to its high temperature dependancy recalculated empirically to reservoir conditions by taking the respective reservoir temperatures into account (<a>[Bär, 2012](#beispiele)</a>; modified after <a>[Vosteen and Schellschmidt, 2003](#beispiele)</a>).
$$ c_{p,m}(T) = 6.295 \cdot 10^{-6} \cdot T^{-3} - 4.99 \cdot 10^{-3} \cdot T^2 + 1.71 \cdot T + c_{p,m,T20} $$
As salinity $S$, temperature, and pressure are influencing parameters of the density of the reservoirs pore fluid $\rho_{brine}$, the following two empirical formulas recalculate the brines density to reservoir consitions under standard conditions (<a>[Batzle and Wang, 1992](#beispiele)</a>).
$$ \rho_{brine} = \rho_{fw} + S \cdot (0.668 + 0.44 S + 10^{-6} \cdot (300p - 2400pS + T \cdot (80 + 3T - 3300S - 13p + 47pS)))$$
$$ \rho_{fw} = 1 + 10^{-6} \cdot ( -80 T - 3.3 T^2 + 0.00175 T^3 + 489p - 2Tp + 0.016 T^2 p - 1.3 \cdot 10^{-5} T^3 p - 0.333 p^2 - 0.002 T p^2)$$
where $p$ is the hydrostatic pressure:
$$p = \rho_{brine_0} \cdot g \cdot h + atm$$
%% Cell type:markdown id: tags:
## Getting started
Before you can run the Heat In Place calculation tool, you need to undertake the following steps:
- Import relevant python packages
- Define your folder locations
- Setup your files to correct format
- Define steady parameters
%% Cell type:markdown id: tags:
### Import python packages
Before you can run the calculation you need to import the following python packages into your python environment:
%% Cell type:code id: tags:
``` python
from ipywidgets import widgets
from IPython.display import display, HTML
```
%% Output
---------------------------------------------------------------------------
ModuleNotFoundError Traceback (most recent call last)
~\AppData\Local\Temp/ipykernel_22332/2683916936.py in <module>
----> 1 from ipywidgets import widgets
2 from IPython.display import display, HTML
ModuleNotFoundError: No module named 'ipywidgets'
%% Cell type:code id: tags:
``` python
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib.cm as cm
from mpl_toolkits.axes_grid1 import make_axes_locatable
from scipy.interpolate import griddata
from pathlib import Path
```
%% Cell type:markdown id: tags:
### Define folder locations
As some datasets might be quite big and things would probably get messy if you wouldn't thoroughly place your data in a suitable folder strucutre, now is the time to define
`input_path` and `output_path` folders and adjust the correct folder path in the script below.
### Define paths
Provided example is organized as follows:
- folder `input_path` contains test data files
- `input_file` represents the file name to be loaded
- `output_path` is the folder to store the results
- `output_path_fig` is the folder to store the resulting figures
Both `output_path` and `output_path_fig` are created after first execution of the script.
In case you want to generate figures aswell, create an aditional folder for `output_path_pic` and further down in this notebook, tick the box asking you to generate figures.
By default the script does not save the figures, in case you want to generate figures as well, enable it in the checkbox further down in this notebook.
User is free to adjust this script to its own needs.
%% Cell type:code id: tags:
``` python
input_path = './test_dataset.csv'
output_path = './results/'
output_path_pic = './results/HIP_pics/'
input_path = './data/' # this folder contains test files
input_file = 'test_dataset.csv' # name of the file to load
output_path = './results/' # this folder will be created and will contain results
output_path_fig = output_path + 'figures/' # this folder will be created and will contain figures
# Create paths:
Path(output_path_fig).mkdir(parents=True, exist_ok=True) # this creates both output paths at once
```
%% Cell type:markdown id: tags:
### File setup
In order to run the caculation smooothly, your input files should follow a specific strucutre that goes well with the formulas used in this tool. The desirable file structure of your input data table must contain the columns pictured here:
**<font color=red>To Judith: Bild Platzhalter: In line 2 replace "images1.jpg" with your image + adjust width (maybe 200px or 300px) </font>**
%% Cell type:markdown id: tags:
<tr>
<td> <img src="images1.jpg" alt="Drawing" style="width: 200px;"/> </td>
<td> <table>
<thead>
<tr>
<th>x</th>
<th>y</th>
<th>$d_{mean}$</th>
<th>$M_{total}$</th>
<th>$T_{mean}$</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
<td>161.0944798</td>
<td>12.69794223</td>
</tr>
<tr>
<td>1004.016064</td>
<td>0</td>
<td>0</td>
<td>160.4305277</td>
<td>12.67989258</td>
</tr>
<tr>
<td>2008.032129</td>
<td>0</td>
<td>0</td>
<td>159.1173317</td>
<td>12.64417627</td>
</tr>
<tr>
<td>...</td>
<td>...</td>
<td>...</td>
<td>...</td>
<td>...</td>
</tr>
</tbody>
</table>
</td>
</tr>
%% Cell type:markdown id: tags:
### Define parameters for calculation
Now, please define several steady parameters for your calculation:
%% Cell type:markdown id: tags:
|variable |description |unit |SI-unit |
|---|---|---|---|
| $g$ | standard gravity | $\frac{m}{s^2}$ | $\frac{m}{s^2}$ |
| $atm$ | atmospheric pressure | $Pa$ | $\frac{kg}{ms^2}$ |
| $T_{ref}$ | temperature at topography,model reference temperature |$°C$ | $K$ |
| $\phi$ | porosity | % | - |
| $\rho_{brine\ 0}$ | density of brine (empirical) | $\frac{kg}{m^3}$ | $\frac{kg}{m^3}$ |
| $Cp_{brine}$ | speciifc heat capacity of brine | $\frac{J}{kgK}$ | $\frac{m^2}{Ks^2}$ |
| $S$ | Salinity of brine | $\frac{kg}{m^3}$ | $\frac{kg}{m^3}$ |
| $\rho_{solid}$ | density of solid | $\frac{kg}{m^3}$ | $\frac{kg}{m^3}$ |
| $Cp_{solid\ 0}$ | speciifc heat capacity of solid (empirical) | $\frac{J}{kgK}$ | $\frac{m^2}{Ks^2}$ |
These steady parameters need to be defined here:
%% Cell type:code id: tags:
``` python
g = 9.81 #[m/s^2]
atm = 101325 #[Pa; kg/(m*s^2)]
Tref = 8 #[°C; K]
Phi = 0.14 #[%]
Rho_brine_0 = 1040 #[kg/m^3]
Cpm_brine = 3.925*1000 #[J/(kg*K); m^2/(K*s^2)]
S = 60 #[kg/m^3]
Rho_solid = 2680 #[kg/m^3]
Cp_solid_0 = 810 #[J/(kg*K); m^2/(K*s^2)]
```
%% Cell type:markdown id: tags:
## Perform calculation
Now, with all preparations done, you should be able to smoothly run the calculation by running the following cells.
<div class="alert alert-block alert-warning">
<b>Be aware:</b> There is one option implemented in the skript which is to additionally generate figures to your calculation output. You can decide whether executing or skipping the option by ticking or unticking the checker box 'Want to generate figures?'.</div>
%% Cell type:markdown id: tags:
### Load files
Firstly, load your file into the script.
%% Cell type:markdown id: tags:
You have to assign the correct header manually in `line 6`, as this is dependant on your personal input table. Here, we assigned the header of the test-dataset.
Use `line 3` (by uncommenting it) if you want to load a `.txt` or `.dat` file and assign the correct delimiter (test-dataset uses space). Use `line 5` if you want to load a `.csv` file. (If your input file is an excel table, save it as Comma Seperated Values file `.csv` first.)
You should see your input data displayed correctly below, if everything has loaded without errors. Make sure to check for correctness here!
%% Cell type:code id: tags:
``` python
# load csv file and assign correct header (dependant on your personal input table)
# line 3 for .txt or .dat files
# df_test = pd.read_csv(input_path, comment='#', delimiter = ' ', header=None)
# df_test = pd.read_csv(input_path + input_file, comment='#', delimiter = ' ', header=None)
# line 5 for .csv
df_test = pd.read_csv(input_path, comment='#', delimiter = ',')
df_test = pd.read_csv(input_path + input_file, comment='#', delimiter = ',')
df_test.columns = ['x', 'y', 'dmean', 'Mtotal', 'Tmean', 'Ztop', 'Zmean']
display(df_test)
```
%% Output
%% Cell type:markdown id: tags:
### Heat In Place calculation
This is the part where your data finally gets transformed into what you aim at.
**Don't change anything in the code cell below! All input and adjustments have been defined in the previous steps!**
%% Cell type:code id: tags:
``` python