Resolve "Package the thermogis jar with pythermogis, thus reducing the installation steps"

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 and store the ThermoGIS Jar (a Java executable file) on your computer:

Because of this dependency you need to Install a Java 17 VM.

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

### 1. Install Java 17

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)) and a [ThermoGIS Jar file](https://ci.tno.nl/gitlab/ags_public/pythermogis/-/blob/main/resources/thermogis_jar/thermogis-1.7.0-shaded.jar?ref_type=heads) (Version >=1.7).

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

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

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

### 2. Create Required Environment Variables

### 2. Ensure JAVA_HOME is set

Create a file called ``.env`` in your project root folder. 

This file should contain the following variables:

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.

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. 

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

- `JAVA_HOME`: Path to the Java 17 installation

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

- `THERMOGIS_JAR`: Path to the ThermoGIS `.jar` file; __including__ the name of the jar file

  *(e.g. `/path/to/the/thermogis-1.7.0-shaded.jar`)*

Example .env contents:

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

```

THERMOGIS_JAR = /path/to/the/thermogis-1.7.0-shaded.jar

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

```

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

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

cd pythermogis

pixi install

```

(Make sure you have followed the step installing a Java17 VM and saving the ThermoGIS Jar)

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

---

# Change log

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

## v1.2.3 (6-1-2026)

Added the calculation of `heat in place` and `potential recoverable heat`. These are part of the potential calculation of the original java code. 

import os

from pathlib import Path

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 the resources directory, return the path to the ThermoGIS Jar

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

    """

    tg_jar = os.getenv("THERMOGIS_JAR")

    if tg_jar is None:

        raise ValueError("THERMOGIS_JAR environment variable is not set in the .env file.")

    thermogis_jar_path = Path(tg_jar)

    if not thermogis_jar_path.exists():

        raise FileNotFoundError(f"Jar file not found at {thermogis_jar_path}, check that you have downloaded the ThermoGIS Jar and set the THERMOGIS_JAR environment variable.")

    return str(thermogis_jar_path)

    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():

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

    :return:

    """

    java_home = os.getenv("JAVA_HOME")

    if java_home is None:

        raise ValueError("JAVA_HOME environment variable is not set in the .env file.")

    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():

from pathlib import Path

THERMOGIS_JAR_PATH = (

    Path(__file__).parent / "thermogis_jar" / "thermogis-1.7.0-shaded.jar"

)