Getting Started

This tutorial walks through a complete thermal analysis of a single buried medium-voltage cable — from defining the cable and load, through running a transient simulation, to inspecting and plotting the results.

Step 1: Define a cable

Thermal Cable Model includes factory methods for common cable constructions. A single-core 240 mm2 copper XLPE cable rated at 20 kV is created with:

from thermal_cable_model import Cable

cable = Cable.single_core_xlpe_cu(240, voltage_class="MV", voltage_kv=20.0)
print(cable.name)                      # "1×240 mm² Cu XLPE 20 kV"
print(f"{cable.outer_diameter*1e3:.1f} mm")  # outer diameter in mm

The factory method builds the insulation, screen, and jacket layers automatically. See Cable Models for how to define custom cables layer-by-layer.

Step 2: Define a load profile

A load profile describes the cable current as a function of time. The simplest case is a constant current:

from thermal_cable_model import LoadProfile

duration = 48 * 3600       # 48 hours in seconds
load = LoadProfile.constant(400.0, duration)  # 400 A for 48 h

Other load shapes are available — see Load Profiles.

Step 3: Set up the installation

A CableInstallation describes the physical arrangement: cable positions, burial depths, soil properties, and the ground temperature model.

from thermal_cable_model import CableInstallation, KasudaModel
from thermal_cable_model.materials import SOIL_STANDARD

ground = KasudaModel(
    mean_surface_temp=10.0,
    annual_amplitude=12.0,
    day_of_min_surface_temp=35.0,
    soil_diffusivity=0.5e-6,
)

inst = CableInstallation(soil=SOIL_STANDARD, ground_temp_model=ground)
inst.add_cable(cable, x=0.0, depth=1.2, load=load)

Step 4: Run the simulation

Wrap the installation in a ThermalSimulation and run either a steady-state or transient analysis:

from thermal_cable_model import ThermalSimulation

sim = ThermalSimulation(inst)

# Steady-state at a particular moment in time
ss = sim.run_steady_state(time_s=200 * 86400)  # mid-summer
print(f"Conductor: {ss.conductor_temps[0, 0]:.1f} °C")

# Transient — 48 hours at 1-minute steps
result = sim.run_transient(dt=60, duration=48 * 3600)
print(f"Max conductor temp: {result.max_conductor_temp(0):.1f} °C")

Step 5: Visualise the results

Built-in plotting functions create publication-ready figures:

from thermal_cable_model import plot_temperature_history

fig = plot_temperature_history(result, time_unit="hours")
fig.savefig("my_cable_temperatures.png", dpi=150)

The plot_temperature_history() function shows conductor, insulation, sheath, armour, surface, and soil node temperatures on one axis with an optional current panel below.

What next?