Merge branch '7-improve-the-readme-md' into 'main'

It uses xarray (https://docs.xarray.dev/en/stable/index.html) Datasets as input to the simulation and can be combined with the pygridsio package (https://pypi.org/project/pygridsio/) to read in and process 2D rasters

### Install via pip from GitLab

## Installation for Usage

To install `pyThermoGIS` into your own project directly from GitLab, run:

### Install from the TNO GitLab

This repository is currently hosted on ci.tno.nl and is currently not available for the public. 

Therefore, to install `pyThermoGIS` from the TNO GitLab repository authentication is required for now. 

Follow these steps:

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

- 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.

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

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

```ini

[gitlab]

repository = https://ci.tno.nl/gitlab/api/v4/projects/18271/packages/pypi

username = __token__

password = <your_personal_token>

```

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

### 3. Install the Package

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

```sh

pip install git+https://gitlab.com/your-repo/pythermogis.git

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

```

This will fetch the latest version from the public GitLab repository.

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

### Notes

- 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.

## Usage

print(doublet_simulation_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:

```python

from pythermogis.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]])),

  "ntg": (("x", "y"), np.array([[0.5, 0.5], [0.25, 0.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)

```

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:

```python

from pythermogis.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["porosity"] = read_grid("porosity.zmap")

input_grids["depth"] = read_grid("top_depth.zmap")

input_grids["mask"] = read_grid("hydrocarbons.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)

```

## Contributing

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

def calculate_temperature_from_gradient(depth: float, thickness: float, degrees_per_km: float, surface_temperature: float):

    return surface_temperature + (depth + thickness / 2) * (degrees_per_km * 0.001)

from typing import List

from pythermogis.thermogis_classes.doublet import calculate_doublet_performance_across_dimensions

import xarray as xr

def calculate_doublet_performance(input_data: xr.Dataset,

                                  input_params: dict = None,

                                  p_values: List[float] = None) -> xr.Dataset:

    """

    An access point to the calculate_doublet_performance_across_dimensions function in pythermogis.thermogis_classes.doublet, see that method for more detailed instruction

    """

    return calculate_doublet_performance_across_dimensions(input_data, input_params=input_params, p_values=p_values)