Resolve "trial use of install-jdk"

# Installation

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

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

It works by creating a 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.

### 1. Install Java 17

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

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

If you wish to build the documentation locally, follow the installation from source step and run:

*(You can find the JAR in this repository's resources folder: /resources/thermogis_jar)*

```bash

pixi run mkdocs serve

```

### 2. Ensure JAVA_HOME is set

---

When installing the Java 17 Virtual Machine (JVM), a global environment variable _should_ have been set: `JAVA_HOME`. This stores the path to the JVM that was installed in step 1 and enables pythermogis to read the core Java code.

# Installation

If, for some reason, this was not done during installation you can either set it yourself or create a ``.env`` file in your project root folder. 

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

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

This `.env` file should contain the following variable:

The ThermoGIS techno-economic Core application is packaged within pythermogis, this is the reason the package is quite large (~150mb).

Additionally the first time you run a simulation with pythermogis, a Java 17 Virtual machine (JVM) will be automatically installed (using the package [install-jdk](https://pypi.org/project/install-jdk/)).

- `JAVA_HOME`: Path to the Java 17 installation

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

The Java 17 virtual machine is an additional ~350mb so there should be at least 500mb of space on any machine you install pythermogis on (and preferably more).

Installation of the JVM can take some time (0.5 - 2 minutes) depending on the speed of your internet connection, but will only be done once per pythermogis installation.

Example `.env` contents (The specific path could be different depending on your OS, or file architecture):

```

JAVA_HOME = C:\Program Files \Amazon Corretto\jdk17.0.0_0

```

pythermogis has been tested on Windows and Linux operating systems.

### 3. Import pythermogis into your own python projects

### 1. Import pythermogis into your own python projects

You can use pip to install the package directly from the gitlab project:

```

uv add pythermogis --default-index https://ci.tno.nl/gitlab/api/v4/projects/18271/packages/pypi/simple

```

### Installation from source

### 2. Installation from source

Clone and install from source with Pixi:

cd pythermogis

pixi install

```

(Make sure you have followed step 1 and 2: installing a Java 17 VM)

---

# Change log

## v1.2.5 (26-1-2026)

A java 17 virtual machine is now automatically installed the first time a pythermogis simulation is run. This uses the [install-jdk](https://pypi.org/project/install-jdk/) python project.

## v1.2.4 (23-1-2026)

The ThermoGIS Jar is now packaged within pythermogis, this reduces the number of installation steps from users (no longer having to set a THERMOGIS_JAR environment variable) and means that multiple installations of pythermogis on the same 

system won't break each-other (previously two or more pythermogis installations would use the same Jar, which could cause version conflicts). 

import faulthandler

import jdk

import jpype

import shutil

from pythermogis.constants import JVM17_DLL_PATH, JVM17_PATH, THERMOGIS_JAR_PATH

def install_jvm():

    """

    Installs a Corretto build of Java 17 JDK, renames it from jdk17_XX_XX to jdk17

    and checks that the executable exists.

    :return:

    """

    print(

        "Installing Java Virtual Machine, this can take some time but will only be "

        "run once."

    )

    # delete path first to ensure fresh installation

    if JVM17_PATH.exists():

        shutil.rmtree(JVM17_PATH)

    # create path

    JVM17_PATH.mkdir(parents=True, exist_ok=True)

    # Installs a Corretto build of Java 17 JDK

    jdk.install("17", vendor="Corretto", path=JVM17_PATH)

    # search for the path of the installed JDK, it can be different depending on the

    # version number

    jdk_dirs = [p for p in JVM17_PATH.glob("*") if p.is_dir()][0]

    # rename to the standard path to be used throughout pythermogis

    shutil.move(jdk_dirs, JVM17_PATH / "jdk17")

    if not JVM17_DLL_PATH.exists():

        raise FileExistsError(

            f"Installation of JVM unsuccessful."

            f"Java virtual machine executable not found at :{JVM17_DLL_PATH}"

        )

def start_jvm():

    """

    To use the JPype package a java .jar file has to be instantiated with a java virtual

    machine (jvm).

    This method ensures a clean startup of the jvm packaged with this repo

    :return:

    """

    if jpype.isJVMStarted():

        return

    # when running pytest with jpype a "Windows fatal exception" is thrown which in

    # reality has no affect on the outcome or performance.

    # the current workaround from the jpype package is to disable the pytest

    # faulthandler. (This will not prevent python or java errors in the test).

    faulthandler.disable()

    if not JVM17_DLL_PATH.exists():

        # If the JVM has not been installed (ie. JVM17_DLL_PATH does not exist, then

        # install using the install-jdk package

        install_jvm()

    if not THERMOGIS_JAR_PATH.exists():

        raise FileNotFoundError(f"Jar file not found at {THERMOGIS_JAR_PATH}.")

    # starts the java virtual machine and loads the thermogis classes

    jpype.startJVM(str(JVM17_DLL_PATH), classpath=[str(THERMOGIS_JAR_PATH)])

import os

import jpype

import faulthandler

from dotenv import load_dotenv

from pythermogis.constants import THERMOGIS_JAR_PATH

load_dotenv()

def get_thermogis_jar_path() -> str:

    """

    From within thermogis, find the thermogis-jar, return the path to the ThermoGIS Jar

    """

    if not THERMOGIS_JAR_PATH.exists():

        raise FileNotFoundError(f"Jar file not found at {THERMOGIS_JAR_PATH}.")

    return str(THERMOGIS_JAR_PATH)

def start_jvm():

    """

    To use the JPype package a java .jar file has to be instantiated with a java virtual machine (jvm)

    This method ensures a clean startup of the jvm packaged with this repo

    :return:

    """

    if not jpype.isJVMStarted():

        # when running pytest with jpype a "Windows fatal exception" is thrown which in reality has no affect on the outcome or performance.

        # the current workaround from the jpype package is to disable the pytest faulthandler. (This will not prevent python or java errors in the test).

        faulthandler.disable()

        # automatically looks up the java version in JAVA_HOME

        jpype.startJVM(classpath=[get_thermogis_jar_path()])

def close_jvm():

    """

    To use the JPype package a java .jar file has to be instantiated with a java virtual machine (jvm)

    This method ensures a clean shutdown of the jvm

    :return:

    """

    if jpype.isJVMStarted():

        jpype.shutdownJVM()

def print_java_path():

    """

    This method prints the path to the JVM being used

    :return:

    """

    print(os.getenv("JAVA_HOME"))

def print_thermogis_jar_path():

    """

    This method prints the path to the Thermogis Jar being used

    :return:

    """

    print(get_thermogis_jar_path())