Getting started

Introduction

TurboMoC designs supersonic nozzles and turbomachinery geometry with a real-fluid thermodynamic core supplied by jaxprop. It includes a conventional rounded-arc solver and a sharp-corner minimum-length-nozzle solver. Both expose a common high-level function and return the same JSON-safe result structure.

The toolkit supports single-phase, saturated two-phase, and subcooled-liquid flashing or wet-to-dry inlet conditions under the Homogeneous Equilibrium Model. Results can be visualized with Matplotlib or Plotly and used to parametrize stator and rotor blades.

Installation instructions

TurboMoC requires Python 3.11, 3.12, or 3.13. Install it with pip in your Python environment:

python -m pip install --upgrade "turbo_moc[cad]"

This also installs CadQuery for STEP geometry export and upgrades an existing TurboMoC installation.

Install from source with Poetry

To install from source with Poetry, clone the repository and install the package with CAD support:

git clone https://github.com/turbo-sim/TurboMoC.git
cd TurboMoC
poetry install --extras cad

Use poetry run python to run Python scripts in the Poetry environment. For development tools and documentation builds, see the Developer guide.

Verify the installation

python -c "import turbo_moc; print(turbo_moc.__version__)"

For a Poetry source installation, prefix this command with poetry run.

Design a nozzle

The public design_nozzle function accepts ordinary Python values and returns a flat dictionary suitable for serialization and plotting.

The conditions below are representative of a transcritical CO₂ heat pump: the nozzle expands CO₂ from a gas-cooler outlet at 35 °C and 1.2 times the critical pressure (about 88.5 bar) to the saturation pressure at an evaporation temperature of 5 °C (about 39.7 bar).

import jaxprop as jxp
import matplotlib.pyplot as plt
from turbo_moc import design_nozzle, mpl

fluid = jxp.Fluid("CO2")
inlet_pressure = 1.2 * fluid.critical_point.p  # Pa
inlet_temperature = 273.15 + 35.0  # K; gas-cooler outlet at 35 °C
evaporation_temperature = 273.15 + 5.0  # K (5 °C)
back_pressure = fluid.get_state(jxp.QT_INPUTS, 0, evaporation_temperature).p

result = design_nozzle(
    fluid_name="CO2",
    P0=inlet_pressure,
    T0=inlet_temperature,  # K
    p_back=back_pressure,  # Pa; saturation pressure at 5 °C
    solver="conventional",
)

print(f"Converged: {result['converged']}")
print(f"Exit Mach number: {result['exit_M']:.4f}")

fig, ax = mpl.plot_characteristics_mesh(result, mirror=True)
plt.show()

Launch the interactive app

turbo_moc-app

For a Poetry source installation, use poetry run turbo_moc-app. Open the local URL printed in the terminal in a browser.

The current app defaults to port 8052. Use turbo_moc-app-legacy for the preserved app on port 8050. After updating a Poetry checkout, refresh the launcher commands with poetry install --only-root.

Continue to the theory, examples, or API reference.