Skip to content

Getting Started

from thermohl.solver import HeatEquationTypefrom thermohl.solver import SolverType<!-- SPDX-FileCopyrightText: 2025 RTE (https://www.rte-france.com)

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. SPDX-License-Identifier: MPL-2.0 -->

Users

Environment

ThermOHL is using pip for project and dependencies management. You need a compatible version of python (3.8 or higher). You may have to install it manually (e.g. with pyenv). Then you may create a virtualenv and activate it.

Set up thermohl

To install the package using pip, execute the following command:

    pip install thermohl

Use it ! You can report to the user guide section. 

    import thermohl
    print(thermohl.__version__)

Logging

By default, the thermohl logger is silent (it uses a logging.NullHandler).

To enable log messages in the console, you can use the provided utility function:

import thermohl.utils
import logging

thermohl.utils.add_stderr_logger(level=logging.INFO)

Alternatively, you can manually configure the thermohl logger using Python's standard logging module:

import logging

logger = logging.getLogger("thermohl")
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
logger.addHandler(handler)

Developers

Install the development dependencies and program scripts via

  uv pip install -e .
  uv sync --group dev

Build a new wheel via

  uv build --wheel

This build a wheel in newly-created dist/ directory

Building the documentation with mkdocs

First, make sure you have mkdocs and the Readthedocs theme installed.

If you use uv, open a terminal and enter the following commands:

  uv sync --group docs

Then, in the same terminal, build the doc with:

  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.

The documentation can then be accessed locally from http://127.0.0.1:8000.

Simple usage

Solvers in thermOHL take a dictionary as an argument, where all keys are strings and all values are either integers, floats or 1D numpy.ndarray of integers or floats. It is important to note that all arrays should have the same size. Missing or None values in the input dictionary are replaced with a default value, available using solver.default_values(), which are read from thermohl/default_values.yaml.

Example 1

This example uses the single-temperature heat equation (1t) with IEEE power terms and default values to compute the surface temperature (°C) of a conductor in steady-state regime along with the corresponding power terms (W.m-1).

from thermohl import solver
from thermohl.solver.entities import HeatEquationType

slvr = solver.ieee(dic=None, heat_equation=HeatEquationType.ONE_TEMPERATURE)
temp = slvr.steady_temperature()

Results from the solver are returned in a dict where values are numpy arrays::

>>> temp
{'temperature': array([27.3325034]),
 'joule_power': array([0.27314919]),
 'solar_power': array([9.73237776]),
 'convection_power': array([6.65130481]),
 'radiation_power': array([3.35422215]),
 'precipitation_power': array([0.]),
 'input_latitude': 45.0,
  ...
 }

Example 2

This example uses the same heat equation and power terms, but to compute the line ampacity (A), ie the maximum power intensity that can be used in a conductor without exceeding a specified maximal temperature (°C), along with the corresponding power terms (W.m-1). We can see that, for three different ambient temperatures, we have three distinct ampacities (and the lower the ambient temperature, the higher the ampacity).

import numpy as np
from thermohl import solver
from thermohl.solver.entities import HeatEquationType

slvr = solver.ieee(dict(ambient_temperature=np.array([0., 15., 30.])), heat_equation=HeatEquationType.ONE_TEMPERATURE)
Tmax = 80.
imax = slvr.steady_intensity(Tmax)

>>> imax
{'transit': array([1605.51693463, 1407.02006847, 1183.54643897]),
 'joule_power': array([83.64586616, 64.2414426 , 45.45538152]),
 'solar_power': array([9.73237776, 9.73237776, 9.73237776]),
 'convection_power': array([66.75078505, 50.88447273, 36.23473652]),
 'radiation_power': array([26.62745888, 23.08934764, 18.95302277]),
 'precipitation_power': 0.0,
 'input_latitude': 45.0,
  ...
 }