updating documentation

The underlying theory of the geothermal doublet simulation is explained in the [theory section](../theory/introduction.md).

- [deterministic doublet](deterministic_doublet.md) page demonstrates how to run a simulation and retrieve results.

- [deterministic doublet](deterministic_doublet.md) page demonstrates how to run a deterministic doublet simulation and retrieve results.

- [stochastic doublet](stochastic_doublet.md) page demonstrates how to run a ThermoGIS stochastic simulation and how to run a simulation for a range of p-values.

- [customized properties](customized_props.md) page explains how to customize the techno-economic properties of the simulation.

- [p-values doublet](pvalues_doublet.md) page demonstrates how to run a simulation for a range of p-values.

- [map run and analysis](maprun_analysis.md) page demonstrating running on maps, including some plotting examples to illustrate the outputs.

- [portfolio run and analysis](portfoliorun_analysis.md) page demonstrating running on a portfolio of prospective locations, including some plotting examples to illustrate the outputs.

### 🧪 Basic Example

This example demonstrates how to run a stochastic doublet simulation using the `calculate_doublet_performance_stochastic` function for a single location. 

This example demonstrates how to run a stochastic doublet simulation using the `calculate_doublet_performance_stochastic` function for a single set of inputs and only the P50. 

The outcomes are stochastic, meaning that different output values can occur with each run.

!!! warning "Permeability vs Log-permeability"

print(results)

```

### 🧪 P-values Example

This example is an extension of the deterministic doublet simulation using the `calculate_doublet_performance_stochastic` function. 

The outcomes correspond to the p-value range of the transmissivity are presented as an expectation curve of transmissivity.

This example corresponds to test case `test_example5` in `test_doc_examples.py` in the `tests` directory of the repository.

```python

from pythermogis import calculate_doublet_performance_stochastic

from matplotlib import pyplot as plt

from pathlib import Path

from os import path

import xarray as xr

output_data_path = Path(path.dirname(__file__), "resources") / "test_output" / "example_data"

input_data = xr.Dataset({

    "thickness_mean": ((), 300),

    "thickness_sd": ((), 50),

    "ntg": ((), 0.5),

    "porosity": ((), 0.5),

    "depth": ((), 2000),

    "ln_permeability_mean": ((), 5),

    "ln_permeability_sd": ((), 0.5),

})

results = calculate_doublet_performance_stochastic(input_data, p_values=[1, 10, 20, 30, 40, 50, 60, 70, 80, 90, 99])

fig, axe = plt.subplots(figsize=(10, 5))

kh = results.transmissivity_with_ntg * 1.0

kh.plot(y="p_value", ax=axe)

axe.set_title(f"Aquifer Net transmissivity\n kH")

temp = input_data.temperature

inj_temp = results.inj_temp.sel(p_value=50, method="nearest")

prd_temp = results.prd_temp.sel(p_value=50, method="nearest")

axe.axhline(50.0, label=f"TEMP res: {temp:.1f} inj: {inj_temp:.1f} prd: {prd_temp:.1f} ",

            ls="--", c="tab:orange")

# axes.axhline(pos, label=f"probability of success: {pos:.1f}%",ls="--", c="tab:orange")

kh50 = kh.sel(p_value=50, method="nearest")

axe.axvline(kh50, ls="--", c="tab:orange")

axe.legend()

axe.set_xlabel("kH [Dm]")

axe.set_ylabel("p-value [%]")

plt.savefig(output_data_path / "kh.png")

```

The other examples from [deterministic doublet](deterministic_doublet.md) can easily be adapted to this stochastic framework.

      - deterministic doublet: usage/deterministic_doublet.md

      - stochastic doublet: usage/stochastic_doublet.md

      - customized properties: usage/customized_props.md

      - pvalues doublet: usage/pvalues_doublet.md

      - map run and analysis: usage/maprun_analysis.md

      - potrfolio run and analysis: usage/portfoliorun_analysis.md

      #- out maps and locations: usage/pvalues_map_locations.md

        "permeability": 200

    })

    results1 = calculate_doublet_performance(reservoir_properties, print_execution_duration=True)

    results1 = calculate_doublet_performance(reservoir_properties)

    results2 = calculate_doublet_performance(reservoir_properties)

    xr.testing.assert_equal(results1, results2)