improving the README.md

# pyThermoGIS

## What can this package do?

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

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

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

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) `Dataset` to handle input and output parameters.

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 *NOT* package 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

## Installation for use in your own projects

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

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

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)

   - `read_package_registry`

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

##### b. Install the Package

##### b. Install pyThermoGIS using pip

```bash

```

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

```

print(results)

```

### Running Doublet simulations with custom simulation parameters

### 🧰 Running Doublet simulations with custom simulation parameters

To adjust properties of the simulation, you can pass a `utc_properties` instance to the calculate_doublet_performance function.

A `utc_properties` instance is a JClass implementation of the Java UTCProperties class. It is generated by using the `utc_properties_builder`, upon which custom properties can be set, and used to build an instance of the `utc_properties`.

Be aware, that you will need access to the ThermoGIS java source code to fully understand what these properties do and not all properties are actually utilised in this python api (especially those which refer to paths to files).

Be aware: that you will need access to the ThermoGIS java source code to fully understand what these properties do and not all properties are actually utilised in this python api (especially those which refer to paths to files).

Common properties to change include:

- `setUseHeatPump(Boolean)`: if true, include a heat-pump when modelling

print(results)

```

If you have a valid configuration file, you can parse a utc_properties class using the method: `instantiate_utc_properties_from_xml`, some example configuration xml files are found in `tests/resources/scenarios`. 

```python

from pythermogis import calculate_doublet_performance, instantiate_utc_properties_from_xml

import xarray as xr

input_data = xr.Dataset({

    "thickness_mean": ((), 300),

    "thickness_sd": ((), 50),

    "ntg": ((), 0.5),

    "porosity": ((), 0.5),

    "depth": ((), 5000),

    "ln_permeability_mean": ((), 5),

    "ln_permeability_sd": ((), 0.5),

})

utc_properties = instantiate_utc_properties_from_xml("path/to/valid/xml/file")

results = calculate_doublet_performance(input_data, utc_properties=utc_properties)

print(results)

```

---

## Contributing

---

## Installation for Development

## 🪛 Installation for Development

### 🛠️ Install from Source with Pixi

def instantiate_utc_properties_from_xml(xml_file: str | Path) -> JClass:

    """Provided the path to an xml scenario file, parse this file for the utc properties; beware, the xml parses does some validation checks, checking that files exist.

    Even if these parameters are not needed by the pyThermoGIS module, if these validation checks fail, the xml parser will fail."""

    Even if these parameters are not needed by the pyThermoGIS module, if these validation checks fail, the xml parser will fail. To get around this set these variables to null"""

    start_jvm()

    root = ET.parse(xml_file).getroot() # Parsing the xml file to a string

    root = ET.parse(xml_file).getroot()

    # change the parameters input_data_directory, results_directory, and temperature_voxet_file to null

    # change the parameters input_data_directory, results_directory, and temperature_voxet_file to null; these parameters are not used by pyThermoGIS, and if they are not null then the UTCXmlParser will check for directory and file

    #   existence and cause the parsing to fail if they do not exist.

    variables = [root.find(variable) for variable in ["input_data_directory", "results_directory", "temperature_voxet_file"]]

    for var in variables:

        var.text = ""

    # Add dummy variables that need to be present, for the xml parsing; but are not required by the calculation

    # ET.SubElement(root, r"ates_minimum_depth__speed_up_calculation_").text = ""

    # parse to string and pass to the utc xml parser

    xmlstr = ET.tostring(root, encoding='utf8', method='xml')

    return JClass("thermogis.properties.parsers.UTCXmlParser")().parse(xmlstr)

    # parse to string and pass to the Java utc xml parser

    return JClass("thermogis.properties.parsers.UTCXmlParser")().parse(ET.tostring(root, encoding='utf8', method='xml'))

def instantiate_utc_properties_builder() -> JClass:

    """

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<project hto="false">

   <application_version>1.4.2</application_version>

   <application_name>ThermoGIS</application_name>

   <input_data_directory/>

   <maps_prefix__can_be_empty_/>

   <results_directory/>

   <output_maps_for_petrel>0.0</output_maps_for_petrel>

   <max_number_of_processors_for_calculations>64.0</max_number_of_processors_for_calculations>

   <aquifer_list__comma_separated__excluding_stacked_aquifers_>NMVFS, NMVFV, NMRFT, NMRFV, NLFFS, NLFFD, NLLFR, NLLFS, KNGLG_KNGLS, KNNSG, KNNSL, KNNSY, KNNSB, KNNSR, KNNSF_KNNSP, SLDNA, SLDND, RNROF, RNSOB, RBMH, RBMDU, RBMDL, RBMVU, RBMVL, RBSHN, ROSL_ROSLU, ROSLL, DCH, DCD</aquifer_list__comma_separated__excluding_stacked_aquifers_>

   <property_grids_file_extension>.asc</property_grids_file_extension>

   <property_grids__in_input_data_directory__stacked_grids_will_be_created_>

      <row_1>Permeability;no;__k.zmap;__K.zmap</row_1>

      <row_2>PermeabilityLNSD;no;__k_lnsd.zmap;__K_lnsd.zmap</row_2>

      <row_3>Porosity;no;__phi.zmap;__PHI.zmap</row_3>

      <row_4>Thickness;no;__thick.zmap;__THICK.zmap</row_4>

      <row_5>ThicknessSD;no;__thick_sd.zmap;__THICK_sd.zmap</row_5>

      <row_6>Depth;no;__top.zmap;__TOP.zmap</row_6>

      <row_7>NetToGross;no;__ntg.zmap;__NTG.zmap</row_7>

      <row_8>Temperature;yes;__temperature.zmap;__TEMPERATURE.zmap</row_8>

      <row_9>HCAccum;yes;__hc_accum.zmap;__HC_ACCUM.zmap</row_9>

      <row_10>BoundaryShapefile;yes;__BoundaryShapefile.shp;__BOUNDARYSHAPEFILE.shp</row_10>

   </property_grids__in_input_data_directory__stacked_grids_will_be_created_>

   <calculate_stacked_aquifers>1.0</calculate_stacked_aquifers>

   <thickness_correlation_factor___1_to_1__0__no_corr_>0.0</thickness_correlation_factor___1_to_1__0__no_corr_>

   <permeability_correlation_factor___1_to_1__0__no_corr_>0.0</permeability_correlation_factor___1_to_1__0__no_corr_>

   <stacked_aquifers>

      <row_1>N_STACKED;NMVFS, NMVFV, NMRFT, NMRFV, NLFFS, NLFFD, NLLFR, NLLFS</row_1>

      <row_2>KN_STACKED;KNGLG_KNGLS, KNNSG, KNNSL, KNNSY, KNNSB, KNNSR, KNNSF_KNNSP</row_2>

      <row_3>SLDN_STACKED;SLDNA, SLDND</row_3>

      <row_4>TR_STACKED;RNROF, RNSOB, RBMH, RBMDU, RBMDL, RBMVU, RBMVL, RBSHN</row_4>

      <row_5>RO_STACKED;ROSL_ROSLU, ROSLL</row_5>

      <row_6>DC_STACKED;DCH, DCD</row_6>

   </stacked_aquifers>

   <copy_aquifer_files>1.0</copy_aquifer_files>

   <aquifer_files__in_input_data_directory_>

      <row_1>_WV.shp;__white_spots.shp</row_1>

      <row_2>__ntg_points.shp;__ntg_points.shp</row_2>

      <row_3>__poro_points.shp;__poro_points.shp</row_3>

      <row_4>__perm_points.shp;__perm_points.shp</row_4>

      <row_5>__points_QC.shp;__points_QC.shp</row_5>

   </aquifer_files__in_input_data_directory_>

   <output_scenario_name>BaseCase</output_scenario_name>

   <aquifers_to_calculate>NMVFS, NMVFV, NMRFT, NMRFV, NLFFS, NLFFD, NLLFR, NLLFS, KNGLG_KNGLS, KNNSG, KNNSL, KNNSY, KNNSB, KNNSR, KNNSF_KNNSP, SLDNA, SLDND, RNROF, RNSOB, RBMH, RBMDU, RBMDL, RBMVU, RBMVL, RBSHN, ROSL_ROSLU, ROSLL, DCH, DCD, N_STACKED, KN_STACKED, SLDN_STACKED, TR_STACKED, RO_STACKED, DC_STACKED</aquifers_to_calculate>

   <pvalues_to_calculate>50, 90, 10, 70, 30</pvalues_to_calculate>

   <xy_grid_size_factor_for_thickness_grid__integer_>4.0</xy_grid_size_factor_for_thickness_grid__integer_>

   <max_undefined_cells__of_surrounding_4__for_interp>3.0</max_undefined_cells__of_surrounding_4__for_interp>

   <scale_factor_for_h_and_lnk_standard_deviations>1.0</scale_factor_for_h_and_lnk_standard_deviations>

   <minimum_production_temperature>70.0</minimum_production_temperature>

   <heating_return_temperature>60.0</heating_return_temperature>

   <maximum_cooling_temperature_range>300.0</maximum_cooling_temperature_range>

   <number_of_samples_for_kh_distribution>20000.0</number_of_samples_for_kh_distribution>

   <exclude_hydrocarbon_areas>1.0</exclude_hydrocarbon_areas>

   <use_boundary_shapefile>0.0</use_boundary_shapefile>

   <optimize_well_distance>1.0</optimize_well_distance>

   <minimum_well_distance>100.0</minimum_well_distance>

   <maximum_well_distance>3000.0</maximum_well_distance>

   <lifetime>50.0</lifetime>

   <max_tvd_stepout_factor>1.0</max_tvd_stepout_factor>

   <rock_density>2700.0</rock_density>

   <rock_heat_capacity>1000.0</rock_heat_capacity>

   <allowed_temperature_drop_as_fraction_of_deltat>0.1</allowed_temperature_drop_as_fraction_of_deltat>

   <maximum_flow>500.0</maximum_flow>

   <well_distance>1500.0</well_distance>

   <target_cop>15.0</target_cop>

   <hydraulic_gradient_injection_water__sodm_max_inj_pres_>0.105</hydraulic_gradient_injection_water__sodm_max_inj_pres_>

   <minimum_pump_pressure>1.0</minimum_pump_pressure>

   <maximum_pump_pressure>600.0</maximum_pump_pressure>

   <tolerance_of_utc_increase___bar_>0.0</tolerance_of_utc_increase___bar_>

   <temperature_from_input_grids>0.0</temperature_from_input_grids>

   <use_3d_temperature_voxet_model>1.0</use_3d_temperature_voxet_model>

   <temperature_voxet_file/>

   <temp_gradient__surface_temp__below__also_used_>31.0</temp_gradient__surface_temp__below__also_used_>

   <net_to_gross>1.0</net_to_gross>

   <surface_temperature>10.0</surface_temperature>

   <kh_cutoff__speed_up_calculation_>1.0</kh_cutoff__speed_up_calculation_>

   <anistropy__kv_kh__for_doubletcalc1d>1.0</anistropy__kv_kh__for_doubletcalc1d>

   <salinity_at_surface__ppm_>0</salinity_at_surface__ppm_>

   <salinity_gradient__ppm_m_>47.0</salinity_gradient__ppm_m_>

   <pump_efficiency>0.6</pump_efficiency>

   <pump_depth>300.0</pump_depth>

   <calculation_segment_length>50.0</calculation_segment_length>

   <outer_diameter__open_aquifer_section_>8.5</outer_diameter__open_aquifer_section_>

   <inner_diameter__cased_surface_top_aquifer_section_>8.5</inner_diameter__cased_surface_top_aquifer_section_>

   <casing_roughness>1.38</casing_roughness>

   <well_trajectory_curvature_scaling_factor__0__vert_wells_>1.1</well_trajectory_curvature_scaling_factor__0__vert_wells_>

   <injector_skin>-1.0</injector_skin>

   <producer_skin>-1.0</producer_skin>

   <economic_lifetime>15.0</economic_lifetime>

   <drilling_time>1.0</drilling_time>

   <heat_exchanger_construction_time>0.0</heat_exchanger_construction_time>

   <heat_exchanger_capex>0.1</heat_exchanger_capex>

   <annual_load_hours>8000.0</annual_load_hours>

   <pump_costs>0.8</pump_costs>

   <pump_replacement_time>5.0</pump_replacement_time>

   <pump_replacement_work_over_costs>0.5</pump_replacement_work_over_costs>

   <annual_opex_base>10000.0</annual_opex_base>

   <annual_opex_per_unit_power>50.0</annual_opex_per_unit_power>

   <annual_opex_per_unit_energy_produced>0.0</annual_opex_per_unit_energy_produced>

   <annual_opex_based_on_capex>0.0</annual_opex_based_on_capex>

   <opex_electricity_purchase_price_for_operations>8.0</opex_electricity_purchase_price_for_operations>

   <well_costs_base>0.375</well_costs_base>

   <well_costs_depth__along_hole__factor>1050.0</well_costs_depth__along_hole__factor>

   <well_costs_depth_2__along_hole__factor>0.3</well_costs_depth_2__along_hole__factor>

   <well_costs_scaling>1.0</well_costs_scaling>

   <capex_base_expenses__excl_wells_>0.0</capex_base_expenses__excl_wells_>

   <capex_variable_expenses__excl_wells_>2300.0</capex_variable_expenses__excl_wells_>

   <capex_contingency>15.0</capex_contingency>

   <tax_rate>20.0</tax_rate>

   <interest_on_loan>5.0</interest_on_loan>

   <inflation>2.0</inflation>

   <required_return_on_equity>15.0</required_return_on_equity>

   <debt_equity>80.0</debt_equity>

   <eia_percentage>0.0</eia_percentage>

   <transmission_costs>0.0</transmission_costs>

   <use_orc>1.0</use_orc>

   <heat_conversion_efficiency>0.6</heat_conversion_efficiency>

   <parasitic_power_fraction_of_net_power>0.0</parasitic_power_fraction_of_net_power>

   <base_temperature>20.0</base_temperature>

   <use_kestin_viscosity>1.0</use_kestin_viscosity>

   <maximum_depth_for_calculations>6000.0</maximum_depth_for_calculations>

   <stimulate_well_s_>0.0</stimulate_well_s_>

   <added_skin_injector__negative_increases_flow_>-3.0</added_skin_injector__negative_increases_flow_>

   <added_skin_producer__negative_increases_flow_>-3.0</added_skin_producer__negative_increases_flow_>

   <maximum_kh_value_for_stimulation>20.0</maximum_kh_value_for_stimulation>

   <stimulation_capex__for_both_wells_>0.5</stimulation_capex__for_both_wells_>

   <use_heat_pump>0.0</use_heat_pump>

   <calculate_cop>1.0</calculate_cop>

   <_minimum__injection_temperature>15.0</_minimum__injection_temperature>

   <goal_temperature>70.0</goal_temperature>

   <coefficient_of_performance>3.0</coefficient_of_performance>

   <heat_pump_capex>600.0</heat_pump_capex>

   <heat_pump_annual_opex>60.0</heat_pump_annual_opex>

   <include__non_sde__electric_power_in_output>1.0</include__non_sde__electric_power_in_output>

   <alternative_heating_price>2.8</alternative_heating_price>

   <application_mode>0.0</application_mode>

   <rosim_settings_file__must_contain__aquifer__layer_/>

   <hto_aquifer_anisotropy>5.0</hto_aquifer_anisotropy>

   <thermal_radius_factor>2.0</thermal_radius_factor>

   <hto_charge_temperature>80.0</hto_charge_temperature>

   <hto_injection_production_period__max_182_days_>120.0</hto_injection_production_period__max_182_days_>

   <rosim_simulation_time__constant_power_after_>5.0</rosim_simulation_time__constant_power_after_>

   <use_power_from_last_rosim_year_for_all_years>0.0</use_power_from_last_rosim_year_for_all_years>

   <hto_minimum_flow_rate__speed_up_calculation_>0.0</hto_minimum_flow_rate__speed_up_calculation_>

   <hto_minimum_depth__speed_up_calculation_>0.0</hto_minimum_depth__speed_up_calculation_>

   <hto_maximum_depth__speed_up_calculation_>500.0</hto_maximum_depth__speed_up_calculation_>

   <hto_filter_fraction__of_aquifer_thickness_>0.8</hto_filter_fraction__of_aquifer_thickness_>

   <hto_clogging_velocity>0.3</hto_clogging_velocity>

   <hto_membrane_filter_index>1.0</hto_membrane_filter_index>

   <hto_depth_multiplication_factor>0.01</hto_depth_multiplication_factor>

   <input__power_utc__scenario_name__must_exist_>BaseCase</input__power_utc__scenario_name__must_exist_>

   <aquifers_for_potential_calculation>NMVFS, NMVFV, NMRFT, NMRFV, NLFFS, NLFFD, NLLFR, NLLFS, KNGLG_KNGLS, KNNSG, KNNSL, KNNSY, KNNSB, KNNSR, KNNSF_KNNSP, SLDNA, SLDND, RNROF, RNSOB, RBMH, RBMDU, RBMDL, RBMVU, RBMVL, RBSHN, ROSL_ROSLU, ROSLL, DCH, DCD, N_STACKED, KN_STACKED, SLDN_STACKED, TR_STACKED, RO_STACKED, DC_STACKED</aquifers_for_potential_calculation>

   <probability_maps__basename__treshold_value_>npv:0, utc:5, power:1, cop:10, kh:5, flowr:100, h:20</probability_maps__basename__treshold_value_>

   <unit_technical_cost_cutoff>5.1</unit_technical_cost_cutoff>

   <unit_technical_cost_cutoff_deep>6.5</unit_technical_cost_cutoff_deep>

   <depth_for_deep_unit_technical_cost_cutoff>4000.0</depth_for_deep_unit_technical_cost_cutoff>

   <p_value_potential_category_1>50.0</p_value_potential_category_1>

   <p_value_potential_category_2__0__not_used_>30.0</p_value_potential_category_2__0__not_used_>

   <p_value_potential_category_3__0__not_used_>10.0</p_value_potential_category_3__0__not_used_>

   <p_value_potential_category_4__0__not_used_>0.0</p_value_potential_category_4__0__not_used_>

   <additional_p_values_for_the_power_probability_map_and_the_recoverable_heat_maps>90, 70</additional_p_values_for_the_power_probability_map_and_the_recoverable_heat_maps>

   <power_value_for_power_probability_map>10.0</power_value_for_power_probability_map>

   <surface_temperature_hip>10.0</surface_temperature_hip>

   <rock_density_hip>2700.0</rock_density_hip>

   <rock_heat_capacity_hip>1000.0</rock_heat_capacity_hip>

   <exclude_hc_areas_for_recov_heat>1.0</exclude_hc_areas_for_recov_heat>

   <min_prod_temperature__potential__recoverable_heat>0.0</min_prod_temperature__potential__recoverable_heat>

   <aquifer_identifier_for_overview_resources__empty__all_>stacked</aquifer_identifier_for_overview_resources__empty__all_>

   <well_distance__0__from__calc_power_utc_>0.0</well_distance__0__from__calc_power_utc_>

   <doublet_geographical_sorting_factor>1.0</doublet_geographical_sorting_factor>

   <annual_load_hours>6000.0</annual_load_hours>

   <doublet_lifetime>30.0</doublet_lifetime>

   <delete_resources_within_shapefile_s___per_aquifer_>0.0</delete_resources_within_shapefile_s___per_aquifer_>

   <delete_shapefiles__in_input_grids_directory_>

      <row_1>shapefile.shp;license header;aquifer name header</row_1>

   </delete_shapefiles__in_input_grids_directory_>

   <classify_resources_by_shapefile_s_>0.0</classify_resources_by_shapefile_s_>

   <classify_shapefiles__in_input_grids_directory_>

      <row_1>shapefile.shp;output name</row_1>

   </classify_shapefiles__in_input_grids_directory_>

   <stochastic_resources__p90_p50_p10_needed_>0.0</stochastic_resources__p90_p50_p10_needed_>

   <number_of_stochastic_realisations>1000.0</number_of_stochastic_realisations>

   <minimum_unit_technical_cost_cutoff>3.0</minimum_unit_technical_cost_cutoff>

   <maximum_unit_technical_cost_cutoff>8.0</maximum_unit_technical_cost_cutoff>

   <minimum_unit_technical_cost_cutoff_deep>4.0</minimum_unit_technical_cost_cutoff_deep>

   <maximum_unit_technical_cost_cutoff_deep>10.0</maximum_unit_technical_cost_cutoff_deep>

   <stochastic_calculation_parameters>

      <row_1>aquiferName;10;0;1</row_1>

   </stochastic_calculation_parameters>

   <input__calc_potential__scenario_name__must_exist_>BaseCase</input__calc_potential__scenario_name__must_exist_>

   <aquifers_to_use_in_overview_calculation>RO_STACKED</aquifers_to_use_in_overview_calculation>

   <mask_file__for_output_geometry_/>

   <xy_grid_size_factor_for_mask_grid>4.0</xy_grid_size_factor_for_mask_grid>

   <max_undefined_cells__of_surrounding_4__for_interp_overview>3.0</max_undefined_cells__of_surrounding_4__for_interp_overview>

   <p_value_overview_potential_category_1>50.0</p_value_overview_potential_category_1>

   <p_value_overview_potential_category_2__0__not_used_>30.0</p_value_overview_potential_category_2__0__not_used_>

   <p_value_overview_potential_category_3__0__not_used_>10.0</p_value_overview_potential_category_3__0__not_used_>

   <p_value_overview_potential_category_4__0__not_used_>0.0</p_value_overview_potential_category_4__0__not_used_>

   <power_category_1>5.0</power_category_1>

   <power_category_2__0__not_used_>7.5</power_category_2__0__not_used_>

   <power_category_3__0__not_used_>10.0</power_category_3__0__not_used_>

   <power_category_4__0__not_used_>20.0</power_category_4__0__not_used_>

   <additional_p_values_for_the_overview_power_probability_map_and_recoverable_heat_maps>90, 70</additional_p_values_for_the_overview_power_probability_map_and_recoverable_heat_maps>

   <power_value_for_overview_power_probability_map>10.0</power_value_for_overview_power_probability_map>

   <input_scenario_name>BaseCase</input_scenario_name>

   <aquifers_to_use_in_overview_calculation>RO_STACKED</aquifers_to_use_in_overview_calculation>

   <minimum_npv_for_portfolio_repeat>1.0</minimum_npv_for_portfolio_repeat>

   <upward_and_downward_change_of_pos>15.0</upward_and_downward_change_of_pos>

   <general_upward_change_of_pos>5.0</general_upward_change_of_pos>

   <maximum_number_of_failures>2.0</maximum_number_of_failures>

   <repeat_potential_in_portfolio>10.0</repeat_potential_in_portfolio>

   <ates_minimum_depth__speed_up_calculation_>0.0</ates_minimum_depth__speed_up_calculation_>

</project>