Merge branch '17-separate-the-jar-and-the-jvm-from-the-code' into 'main'

  <component name="PyNamespacePackagesService">

    <option name="namespacePackageFolders">

      <list>

        <option value="$MODULE_DIR$/pythermogis/resources" />

        <option value="$MODULE_DIR$/resources" />

        <option value="$MODULE_DIR$/pythermogis" />

      </list>

    </option>

        <entryData>

          <resourceRoots>

            <path value="file://$PROJECT_DIR$/src/resources" />

            <path value="file://$PROJECT_DIR$/pythermogis/resources" />

            <path value="file://$PROJECT_DIR$/pythermogis/resources/java" />

            <path value="file://$PROJECT_DIR$/pythermogis/resources/thermogis_jar" />

            <path value="file://$PROJECT_DIR$/resources" />

            <path value="file://$PROJECT_DIR$/resources//java" />

            <path value="file://$PROJECT_DIR$/resources//thermogis_jar" />

          </resourceRoots>

        </entryData>

      </entry>

# pyThermoGIS

pyThermoGIS is a Python package that provides API access to the [ThermoGIS](https://www.thermogis.nl/en) Geothermal simulation. The simulations are conducted in java and this code uses the JPype package as a python-java

binding.

**pyThermoGIS** is a Python package that provides API access to the [ThermoGIS](https://www.thermogis.nl/en) geothermal simulation software. 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) Datasets as input to the simulation and can be combined with the [pygridsio](https://pypi.org/project/pygridsio/) package  to read in and process 2D rasters

It uses [xarray](https://docs.xarray.dev/en/stable/index.html) `Dataset` as input and can be combined with the [pygridsio](https://pypi.org/project/pygridsio/) package to read and process 2D raster data.

## Installation for usage in your own python project

---

### Install from the TNO GitLab

This repository is hosted on ci.tno.nl and is currently not available for the public. The plan is that this shall be a publically available repository in the near future.

For now, to install `pyThermoGIS` from the TNO GitLab repository into your own python projects; authentication is required.

## Installation

Follow these steps:

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

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

This module requires a Java 17 VM. We recommend using [Amazon Corretto 17](https://docs.aws.amazon.com/corretto/latest/corretto-17-ug/downloads-list.html).

- Log in to GitLab.

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

- Create a new token with the **read_api** and **read_package_registry** scopes.

- Copy the token and store it securely, as it will not be visible again.

#### 🧱 Required Environment Variables

- `JAVA_HOME`: Path to the Java 17 installation

  *(e.g., on Windows: `C:\Program Files\Amazon Corretto\jdk17.0.0_0`)*

### 2. Install the Package

- `THERMOGIS_JAR`: Path to the ThermoGIS `.jar` file

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

Once the `.pypirc` file is set up, install `pyThermoGIS` using:

---

```sh

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

```

### 2. Install pyThermoGIS from TNO GitLab

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

#### 🔐 Step-by-step Installation

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

1. Log in to 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).

This will fetch the package from the specified GitLab package repository.

##### b. Install the Package

### Notes

```bash

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

```

- If you have multiple package sources configured, you may need to use `--extra-index-url` instead of `--index-url`.

- Ensure your `.pypirc` file is stored securely, as it contains authentication credentials.

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

---

## Usage

Here’s a simple example demonstrating how to use `pyThermoGIS` for a single set of input values:

### 🧪 Basic Example

```python

from pythermogis.pythermogis import calculate_doublet_performance

from pythermogis import calculate_doublet_performance

import xarray as xr

# Initialize an input Dataset with the required input variables:

input_data = xr.Dataset({

    "thickness_mean": ((), 300),

    "thickness_sd": ((), 50),

    "ln_permeability_sd": ((), 0.5),

})

# Simulate a Geothermal doublet using the ThermoGIS methodology

doublet_simulation_results = calculate_doublet_performance(input_data)

# Display results

print(doublet_simulation_results)

results = calculate_doublet_performance(input_data)

print(results)

```

The API utilizes xarray's ability to efficiently calculate over multiple dimensions; so you can also provide a grid of values in the input_data and the calculate_doublet_performance method will honour the input 

dimensions:

---

### 🌍 2D Grid Example

```python

from pythermogis.pythermogis import calculate_doublet_performance

from pythermogis import calculate_doublet_performance

import xarray as xr

import numpy as np

# Initialize an input Dataset with the required input variables:

input_data = xr.Dataset({

    "thickness_mean": (("x", "y"), np.array([[300, 300], [200, 200]])),

    "thickness_sd": (("x", "y"), np.array([[50, 50], [25, 25]])),

    "porosity": (("x", "y"), np.array([[0.5, 0.5], [0.75, 0.7]])),

    "depth": (("x", "y"), np.array([[5000, 5000], [4500, 4500]])),

    "ln_permeability_mean": (("x", "y"), np.array([[5, 5], [4.5, 4.5]])),

   "ln_permeability_sd": (("x", "y"), np.array([[0.5, 0.5], [0.75, 0.75]]))},

   coords=dict(

      x=("x", [0, 1]),

      y=("y", [10, 20]),

   )

)

# Simulate a Geothermal doublet using the ThermoGIS methodology

doublet_simulation_results = calculate_doublet_performance(input_data)

# Display results

print(doublet_simulation_results)

    "ln_permeability_sd": (("x", "y"), np.array([[0.5, 0.5], [0.75, 0.75]])),

}, coords={"x": [0, 1], "y": [10, 20]})

results = calculate_doublet_performance(input_data)

print(results)

```

Consider utilizing the pypi package pygridsio to read in and write out 2D raster grids (with either .asc, .zmap, .nc, .tif file formats) to a xarray dataset, before applying the calculate_doublet_performance code:

---

### 🗺️ Reading Raster Grids with pygridsio

```python

from pythermogis.pythermogis import calculate_doublet_performance

from pythermogis import calculate_doublet_performance

from pygridsio.pygridsio import read_grid

# Initialize an input Dataset with the required input variables:

input_grids = read_grid("thickness.zmap").to_dataset(name="thickness_mean")

input_grids["thickness_sd"] = read_grid("thickness_sd.zmap")

input_grids["ntg"] = read_grid("ntg.zmap")

input_grids["ln_permeability_mean"] = read_grid("ln_perm.zmap")

input_grids["ln_permeability_sd"] = read_grid("ln_perm_sd.zmap")

# Simulate a Geothermal doublet using the ThermoGIS methodology

doublet_simulation_results = calculate_doublet_performance(input_grids)

# Display results

print(doublet_simulation_results)

results = calculate_doublet_performance(input_grids)

print(results)

```

---

## Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

## License

---

This project is licensed under the MIT License. See `LICENSE` for details.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.

## Installation for further development

---

### Install from Source with Pixi for further Development

## Installation for Development

To install `pyThermoGIS` from source using Pixi, follow these steps:

### 🛠️ Install from Source with Pixi

1. Clone the repository:

   ```sh

```bash

git clone https://gitlab.com/your-repo/pythermogis.git

cd pythermogis

   ```

2. Ensure Pixi is installed:

   ```sh

   curl -sSL https://pixi.sh/install.sh | bash

   ```

3. Install dependencies and create an isolated environment:

   ```sh

pixi install

```

4. Activate the environment:

   ```sh

   pixi run python

   ```

### Publish to ci.tno.nl/gitlab

---

### 📦 Publish to ci.tno.nl/gitlab

#### 1. Configure `.pypirc`

### 1. Set Up Authentication with `.pypirc`

Create a `.pypirc` file in your home directory:

Create a `.pypirc` file in your home directory (`~/.pypirc` on Linux/macOS or `%USERPROFILE%\.pypirc` on Windows) with the following content:

- Linux/macOS: `~/.pypirc`

- Windows: `%USERPROFILE%\.pypirc`

```ini

[distutils]

password = <your_personal_token>

```

Replace `<your_personal_token>` with your actual GitLab PAT. Ensure the token has the necessary permissions to write to repositories

> Replace `<your_personal_token>` with your GitLab PAT.

### 2. download packages and build project

---

Using Pixi download build and twine, then run:

   ```sh

#### 2. Build the Package

```bash

pixi run python -m build

```

this will then build a .whl and a .tar.gz file and place it in the /build directory

This will generate `.whl` and `.tar.gz` files in the `dist/` directory.

---

### 3. upload to gitlab

#### 3. Upload to GitLab

Then run:

   ```sh

```bash

pixi run twine upload -r gitlab-pythermogis dist/*

```

If the credentials have been successfully updated in the `~/.pypirc` file, this should upload the python package to the gitlab pypi package repository

 No newline at end of file

If `.pypirc` is set up correctly, this will upload the package to the GitLab registry.

                      ADDITIONAL INFORMATION ABOUT LICENSING

Certain files distributed by Oracle America, Inc. and/or its affiliates are 

subject to the following clarification and special exception to the GPLv2, 

based on the GNU Project exception for its Classpath libraries, known as the 

GNU Classpath Exception.

Note that Oracle includes multiple, independent programs in this software 

package.  Some of those programs are provided under licenses deemed 

incompatible with the GPLv2 by the Free Software Foundation and others. 

For example, the package includes programs licensed under the Apache 

License, Version 2.0 and may include FreeType. Such programs are licensed 

to you under their original licenses. 

Oracle facilitates your further distribution of this package by adding the 

Classpath Exception to the necessary parts of its GPLv2 code, which permits 

you to use that code in combination with other independent modules not 

licensed under the GPLv2. However, note that this would not permit you to 

commingle code under an incompatible license with Oracle's GPLv2 licensed 

code by, for example, cutting and pasting such code into a file also 

containing Oracle's GPLv2 licensed code and then distributing the result. 

Additionally, if you were to remove the Classpath Exception from any of the 

files to which it applies and distribute the result, you would likely be 

required to license some or all of the other code in that distribution under 

the GPLv2 as well, and since the GPLv2 is incompatible with the license terms 

of some items included in the distribution by Oracle, removing the Classpath 

Exception could therefore effectively compromise your ability to further 

distribute the package. 

Failing to distribute notices associated with some files may also create 

unexpected legal consequences.

Proceed with caution and we recommend that you obtain the advice of a lawyer 

skilled in open source matters before removing the Classpath Exception or 

making modifications to this package which may subsequently be redistributed 

and/or involve the use of third party software.

OPENJDK ASSEMBLY EXCEPTION

The OpenJDK source code made available by Oracle America, Inc. (Oracle) at

openjdk.java.net ("OpenJDK Code") is distributed under the terms of the GNU

General Public License <http://www.gnu.org/copyleft/gpl.html> version 2

only ("GPL2"), with the following clarification and special exception.

    Linking this OpenJDK Code statically or dynamically with other code

    is making a combined work based on this library.  Thus, the terms

    and conditions of GPL2 cover the whole combination.

    As a special exception, Oracle gives you permission to link this

    OpenJDK Code with certain code licensed by Oracle as indicated at

    http://openjdk.java.net/legal/exception-modules-2007-05-08.html

    ("Designated Exception Modules") to produce an executable,

    regardless of the license terms of the Designated Exception Modules,

    and to copy and distribute the resulting executable under GPL2,

    provided that the Designated Exception Modules continue to be

    governed by the licenses under which they were offered by Oracle.

As such, it allows licensees and sublicensees of Oracle's GPL2 OpenJDK Code

to build an executable that includes those portions of necessary code that

Oracle could not provide under GPL2 (or that Oracle has provided under GPL2

with the Classpath exception).  If you modify or add to the OpenJDK code,

that new GPL2 code may still be combined with Designated Exception Modules

if the new code is made subject to this exception by its copyright holder.