TNO Intern

Commit 89b16f61 authored by Hen Brett's avatar Hen Brett 🐔
Browse files

Merge branch '58-add-disclaimer-and-goforward-logo-to-the-docs-and-the-readme-md' into 'main' 

Resolve "Add disclaimer and GoForward logo to the Docs and the README.md"

Closes #58

See merge request AGS/pythermogis!73
parents c42596d6 d6985946

LICENSE

+4 −5
Original line number Diff line number Diff line 
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:



The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 No newline at end of file
 
The applicable license agreement applies to software which may be downloaded from this website. 

Except insofar as provided otherwise in the applicable license agreement the software is only provided for use by end users and any further copying, reproduction or redistribution of the software is expressly forbidden. 

Any warranties with respect to such software will only apply as explicitly set forth in the applicable license agreement. 

TNO expressly disclaims any further warranties of any kind, including warranties of merchantability, f
 
 No newline at end of file

README.md

+39 −92
Original line number Diff line number Diff line 
# pyThermoGIS



**pyThermoGIS** is a Python package that provides API access to the [ThermoGIS](https://www.thermogis.nl/en) doublet simulations and economic calculations.

**pyThermoGIS** is a Python package that provides API access to the [ThermoGIS](https://www.thermogis.nl/en) doublet simulations and economic calculations,  ThermoGIS is developed and maintained by the [Geological Survey of the Netherlands](https://www.geologischedienst.nl/en/) which is part of [TNO](https://www.tno.nl/en/), additionally, pythermogis was also partially developed by and for the [GoForward](https://go-forward-project.eu/) project.



Read the full documenation [here](https://pythermogis-15909e.ci.tno.nl/).



If you wish to build the documentation locally, run:

If you wish to build the documentation locally, follow the installation steps and run:



```bash

pixi run mkdocs serve

```



## What can this package do?



This package allows a user to simulate geothermal doublets providing the following parameters: 

- Top depth

- Thickness (mean & standard deviation)

- Porosity

- Permeability (mean & standard deviation)

- Temperature (Optional: if not provided, a temperature gradient will be used)





The code will simulate a Geothermal doublet, utilizing ThermoGIS with DoubletCalc1D as the engine to produce values of:



- power [Mega Watt Hour]

- heat pump power [Mega Watt Hour]

- capex (Capital expenditure) [Million €]

- opex (Operational expenditure) [€/kW]

- utc (Unit Technical Cost [€cent/kWH])

- npv (Net-present-value) [Million €]

- hprod (Discounted Heat Produced)

- cop 

- cophp

- pressure 

- flow rate [m³/hr]

- reservoir depth [m]

- injection temperature [C]

- production temperature [C]



For details on how these parameters are calculated we refer users to the [Thermogis calculation webpage](https://www.thermogis.nl/en/calculation-model) and documentation page of pythermogis



The simulations are conducted in Java, and this package uses [JPype](https://jpype.readthedocs.io/en/latest/userguide.html) to create a Python-Java binding.



It uses [xarray](https://docs.xarray.dev/en/stable/index.html) to handle input and output parameters, a User should inform themselves and learn the usage of the Xarray package.



This module can be combined with the [pygridsio](https://pypi.org/project/pygridsio/) package to read and process 2D raster data.



## What can this package *not* do?

This package provides a narrow access point to the doublet simulations and UTC economic calculations from ThermoGIS, it does not implement the following ThermoGIS processes/methodologies:



- Stacking of Aquifers

- Calculation of Potential maps

- Calculation of Resources

- Calculation of Overview maps

- HTO-ATES simulations

- Property Modelling

- Temperature Modelling

- Reading, and writing of grid files (Checkout [pygridsio](https://pypi.org/project/pygridsio/))



---



# Installation



PyThermoGIS has been designed to be used in one of two ways; either as a python package you import into your own python projects, or as a standalone package where you can access the calculations via a CLI.

Either way, you need to Install a Java 17 VM and store the ThermoGIS Jar:

PyThermoGIS has been designed to be used as a python package you import into your own python projects.

It works by creating python API access to the ThermoGIS techno-economic application, which is written in Java. 

Because of this dependency you need to Install a Java 17 VM and store the ThermoGIS Jar (a Java executable file):



### 1. Install Java 17 and Download the ThermoGIS JAR
@@ -80,17 +32,17 @@ This package requires a Java 17 VM (we recommend using [Amazon Corretto 17](http 


---



### 2a) import pyThermoGIS into your own python projects

### Import pyThermoGIS into your own python projects



This repository is currently hosted privately on [ci.tno.nl](https://ci.tno.nl) and will become publicly available in the future. 

This repository is currently hosted privately on [ci.tno.nl](https://ci.tno.nl) and is only accessible to TNO employees. The intention is that this package will become publicly available in the near future. 



Until then you will need to use Gitlab API keys to use this module:

Until then, you will need to use Gitlab API keys to use this module:



#### 🔐 Step-by-step Installation



##### a. Create a Personal Access Token (PAT)



1. Log in to GitLab.

1. Log in to the TNO GitLab.

2. Navigate to **Preferences > Access Tokens**.

3. Create a token with the following scopes:

   - `read_api`
@@ -103,11 +55,11 @@ Until then you will need to use Gitlab API keys to use this module: 
pip install pythermogis --index-url https://__token__:<your_personal_token>@ci.tno.nl/gitlab/api/v4/projects/18271/packages/pypi/simple

```



> 💡 If you already use another index, consider using `--extra-index-url` instead.

replacing the `<your_personal_token>` with the token you created above.



---



### 2b) Installation for further development or Standalone usage

### Installation for further development



Clone and install from source with Pixi:
@@ -118,36 +70,6 @@ pixi install 
```

(Make sure you have followed the step installing a Java17 VM and saving the ThermoGIS Jar)



---



# Usage



PyThermoGIS has been designed to be used in one of two ways; either as a python package you import into your own python projects, or as a standalone package where you can access the calculations via a CLI.





## 1. Running the PyThermoGIS CLI



PyThermogis supports a Command Line Interface (CLI), to see the available commands run the following:



```bash

pixi run pytg --help

```



Currently the main command that can be run is to run a doublet simulation on single values (no grid or arrays) for a P50 simulation. To view the help documentation run:



```bash

pixi run pytg simulate-doublet --help

```



And as an example:



```bash

pixi run pytg simulate-doublet --depth 500 --temperature 150 --thickness 200 --ntg 0.45 --porosity 0.45 --permeability 200 --output-file test.csv

```



## 2. Usage in your own python projects





---



## Contributing
@@ -156,6 +78,31 @@ Contributions are welcome! Feel free to open issues or submit pull requests. 


---



## License



This project is licensed under the MIT License. See the `LICENSE` file for details.
 
 No newline at end of file
 
## License & Disclaimer



This software falls under the same licence and disclaimer for the ThermoGIS project ([English](https://www.thermogis.nl/en/disclaimer), [Nederlands](https://www.thermogis.nl/disclaimer)).



We would like to especially highlight that pythermogis is an *indicative* tool for assessing Geothermal potential and the following statement from the ThermoGIS Disclaimer applies:



> **Exclusion of liability**

> 

>With the exception of statutory liability on the grounds of mandatory legal provisions, TNO, its directors, managers and employees will never be liable in respect of direct and/or indirect,

immaterial or consequential damage including lost profit or income and loss of contracts or orders which in any way results from or is connected with, but does not have to be limited to:

defects, viruses or other faults in equipment and other software in connection with access to or use of this website;

the information which is offered on or via this website;

the interception, modification or improper use of information sent to TNO or to you;

the operation or unavailability of this website;

misuse of this website;

loss of data;

downloading or using software made available through this website, or

claims of third parties in connection with the use of this website.

The exclusion of liability also applies if TNO has been informed of the possibility that such damage may occur.



Along with the following statement on the use of software:



> **Use of Software**

> 

>The applicable license agreement applies to software which may be downloaded from this website. 

Except insofar as provided otherwise in the applicable license agreement the software is only provided for use by end users and any further copying, reproduction or redistribution of the software is expressly forbidden. 

Any warranties with respect to such software will only apply as explicitly set forth in the applicable license agreement. 

TNO expressly disclaims any further warranties of any kind, including warranties of merchantability, fitness for any particular purpose or the non-infringement with respect to the software.
 
 No newline at end of file

docs/images/GO-Forward-gros_transparent.png

0 → 100644
+25.7 KiB
Loading image diff...

docs/index.md

+15 −6
Original line number Diff line number Diff line 
# pyThermoGIS



**pyThermoGIS** is a Python package that provides API access to the [ThermoGIS](https://www.thermogis.nl/en) doublet simulations and economic calculations,  ThermoGIS is developed by the [Geological Survey of the Netherlands](https://www.geologischedienst.nl/en/) which is part of [TNO](https://www.tno.nl/en/).

**pyThermoGIS** is a Python package that provides API access to the [ThermoGIS](https://www.thermogis.nl/en) doublet simulations and economic calculations,  ThermoGIS is developed and maintained by the [Geological Survey of the Netherlands](https://www.geologischedienst.nl/en/) which is part of [TNO](https://www.tno.nl/en/), additionally, pythermogis was also partially developed by and for the [GoForward](https://go-forward-project.eu/) project.





<div style="display: flex; gap: 10px;">

  <img src="../images/pyThermoGIS_transparent.png" style="width: 20%; max-width: 600px; height: auto;">

  <img src="../images/GeologischeDienstlogo.png" alt="Image 1" style="width: 100%; max-width: 600px; height: auto;">

</div>

<div style="display: flex; gap: 10px;">

  <img src="../images/pyThermoGIS_transparent.png" style="width: 15%; max-width: 400px; height: auto;">

  <img src="../images/GeologischeDienstlogo.png" alt="Image 1" style="width: 50%; max-width: 400px; height: auto;">

  <img src="../images/TNOLogo.jpg" alt="Image 1" style="width: 25%; max-width: 400px; height: auto;">

  <img src="../images/TNOLogo.jpg" alt="Image 1" style="width: 25%; max-width: 600px; height: auto;">

  <img src="images/GO-Forward-gros_transparent.png" style="width: 90%; max-width: 600px; height: auto;">

</div>



The intended usage of this pacakge is to import into your own projects so you can run your own doublet simulations using your own input parameters or statistical frameworks.







# Usage

The intended usage of this pacakge is to import into your own projects so you can run your own doublet simulations.



Detailed examples can be found in the [usage](usage/contents.md) documentation page.



This package allows a user to simulate geothermal doublets providing the following parameters:
@@ -40,7 +50,6 @@ The reason to do so is to avoid attributing produced energy which is not renewab 


For details on how these parameters are calculated we refer users to the theory section as well as [Thermogis calculation webpage](https://www.thermogis.nl/en/calculation-model).





For energy conversion to electricity, and chill the power concerns net electricty production and net chill respectively



The simulations are conducted in Java, and this package uses [JPype](https://jpype.readthedocs.io/en/latest/userguide.html) to create a Python-Java binding.

docs/install/install.md

+14 −14
Original line number Diff line number Diff line 
# Installation



PyThermoGIS has been designed to be used as a package you import into your own projects. 

A number of examples have been provided to show how to setup your own simulations and develop your own statistical frameworks.

# Installation



Under the hood PyThermoGIS runs the ThermoGIS code, which is written in Java, so you need to install a Java interpreter and have a file of the ThermoGIS Jar:

PyThermoGIS has been designed to be used as a python package you import into your own python projects.

It works by creating python API access to the ThermoGIS techno-economic application, which is written in Java. 

Because of this dependency you need to Install a Java 17 VM and store the ThermoGIS Jar (a Java executable file):



## 1. Install Java 17 and Download the ThermoGIS JAR

### 1. Install Java 17 and Download the ThermoGIS JAR



This package requires a Java 17 VM (we recommend using [Amazon Corretto 17](https://docs.aws.amazon.com/corretto/latest/corretto-17-ug/downloads-list.html)) and a ThermoGIS Jar file (Version >=1.7).



*(You can find the JAR in this repository's resources folder or request it via the [ThermoGIS website](https://www.thermogis.nl/).)*



### 🧱 Required Environment Variables

#### 🧱 Required Environment Variables



- `JAVA_HOME`: Path to the Java 17 installation

  *(e.g., on Windows: `C:\Program Files\Amazon Corretto\jdk17.0.0_0`)*
@@ -21,34 +21,34 @@ This package requires a Java 17 VM (we recommend using [Amazon Corretto 17](http 


---



## import pyThermoGIS into your own python projects

### Import pyThermoGIS into your own python projects



This repository is currently hosted privately on [ci.tno.nl](https://ci.tno.nl) and will become publicly available in the future. 

This repository is currently hosted privately on [ci.tno.nl](https://ci.tno.nl) and is only accessible to TNO employees. The intention is that this package will become publicly available in the near future. 



Until then you will need to use Gitlab API keys to use this module:

Until then, you will need to use Gitlab API keys to use this module:



### 🔐 Step-by-step Installation

#### 🔐 Step-by-step Installation



##### a. Create a Personal Access Token (PAT)



1. Log in to GitLab.

1. Log in to the TNO GitLab.

2. Navigate to **Preferences > Access Tokens**.

3. Create a token with the following scopes:

   - `read_api`

   - `read_package_registry`

4. Copy and store the token securely (you won’t be able to see it again).



#### b. Install pyThermoGIS using pip

##### b. Install pyThermoGIS using pip



```

pip install pythermogis --index-url https://__token__:<your_personal_token>@ci.tno.nl/gitlab/api/v4/projects/18271/packages/pypi/simple

```



> 💡 If you already use another index, consider using `--extra-index-url` instead.

replacing the `<your_personal_token>` with the token you created above.



---



### 2b) Installation for further development or Standalone usage

### Installation for further development



Clone and install from source with Pixi: