Thermo-Calc’s graphical interface is excellent for interactive, exploratory work — building a phase diagram for a specific alloy, running a Scheil solidification on a new composition, checking equilibrium phase fractions at a particular temperature. But there are entire categories of materials science work where clicking through a GUI is not the right approach: screening thousands of alloy compositions, building databases of thermodynamic properties for machine learning models, coupling CALPHAD calculations into finite element simulations, or running the same property calculation every time a composition parameter changes in an optimization loop.
For all of this, TC-Python exists.
This guide explains what TC-Python is, what it can calculate, how it works in practice, and when it makes sense to use it over the graphical interface.
What Is TC-Python?
TC-Python is a Python SDK (Software Development Kit) that gives you programmatic access to Thermo-Calc calculations from Python code. It is built on the same underlying computational engine as the Thermo-Calc graphical interface — the same databases, the same algorithms, the same results — but accessed through a Python API rather than a point-and-click interface.
The key technical detail: TC-Python is not a wrapper that calls the Thermo-Calc GUI. It is directly linked to the underlying Thermo-Calc code, so it runs at the same computational speed as Thermo-Calc itself and is updated whenever Thermo-Calc is updated. When Thermo-Calc 2026a was released on January 21, 2026, TC-Python was updated simultaneously to support all 2026a features including the Aqueous Calculator and EBM in the AM Module.
TC-Python requires:
- A Thermo-Calc license (TC-Python is an add-on to the base Thermo-Calc license)
- At least one thermodynamic and properties database
- Python 3.x installed on your system
It runs on Windows, macOS, and Linux — all platforms supported by Thermo-Calc.
Why Use TC-Python Instead of the Graphical Interface?
The graphical interface is the right tool for:
- Exploratory work where you don’t know exactly what you’re looking for
- Setting up a new type of calculation for the first time
- Visual inspection of results before committing to an automated workflow
- Teaching and learning
TC-Python is the right tool for:
High-throughput compositional screening. If you need to calculate equilibrium phase fractions at 700°C for 5,000 alloy compositions varying across six elements — do it in TC-Python in a loop or batch calculation. Doing it manually in the GUI would take weeks. With TC-Python and BatchEquilibriumCalculation, it runs automatically, potentially in parallel.
Reproducible, automated workflows. A Python script is version-controlled, shareable, and rerunnable. When you revise a database and want to re-run all your previous calculations against the new parameters, TC-Python makes this trivial. With the GUI, it’s tedious.
Coupling CALPHAD with other software. When your finite element code needs thermodynamic properties at each mesh point, or your machine learning pipeline needs CALPHAD-generated training data, TC-Python is the interface. You call Thermo-Calc calculations from within your existing Python workflow.
Custom post-processing and visualization. TC-Python returns results as Python objects (numbers, arrays). You use Matplotlib, Seaborn, Plotly, or any other Python visualization library to plot exactly what you need, in the format you need it. The graphical interface’s built-in plots are convenient but not always what you need for publications or specialized analysis.
Integration with NumPy, SciPy, Pandas, TensorFlow, PyTorch. Materials informatics workflows that use machine learning to predict alloy properties or guide alloy design frequently use Thermo-Calc as the physics engine that generates training data or validates ML predictions. This integration happens through TC-Python.
What TC-Python Can Calculate
TC-Python exposes essentially all calculations available in Thermo-Calc. Here is the complete functional inventory:
1. Single Equilibrium Calculations
The most fundamental calculation type. Given a system (elements + database), a temperature, a pressure, and a composition, calculate the equilibrium state: which phases are present, their fractions, their compositions, and any thermodynamic property you specify.
Typical properties retrievable:
- Phase fractions (mole or mass)
- Phase compositions (mole or mass fractions of each element in each phase)
- Thermodynamic properties: Gibbs energy (G), enthalpy (H), entropy (S), heat capacity (Cp), chemical potential (μ)
- Physical properties (if property database is included): molar volume, density, thermal conductivity, electrical resistivity
- Transformation temperatures: solidus, liquidus, solvus (using fixed phase conditions)
- Driving forces for phase formation
Practical use case: Calculate austenite fraction as a function of carbon content in a steel at a specific austenitizing temperature. Or: find the solidus temperature of a nickel superalloy composition. Or: check whether a σ-phase forms in an austenitic stainless steel at 750°C.
2. Batch Equilibrium Calculations
BatchEquilibriumCalculation is specifically optimized for calculating many equilibria where each individual calculation is fast (systems with few or non-complicated phases). For evaluating single-phase properties across thousands of compositions, it provides significantly higher throughput than running individual equilibria in a loop.
Practical use case: Evaluate FCC phase density for 10,000 Al-Si-Cu alloy compositions with varying Cu content. Build a composition-density database for machine learning feature engineering.
3. Property Diagrams (Step Calculations)
Calculate a thermodynamic property as a continuous function of one variable (typically temperature or composition), producing the equivalent of Thermo-Calc’s property diagram.
Practical use case: Calculate phase fractions vs. temperature for a multicomponent steel from room temperature to liquidus. Or: calculate Cp vs. temperature for input to a heat treatment simulation.
4. Phase Diagrams
Calculate and plot binary or ternary phase diagrams, or isopleth (pseudo-binary) sections of multicomponent phase diagrams.
Practical use case: Calculate the Fe-Cr phase diagram to identify the α/γ/α+γ fields. Or: calculate an isopleth through a nickel superalloy composition space to identify the γ’ solvus as a function of Al content.
5. Scheil Solidification Calculations
Simulate non-equilibrium solidification using the Scheil-Gulliver model (no diffusion in solid, perfect mixing in liquid). Returns the solidification path, phase sequence, microsegregation profiles, and solidification range.
Variants available:
- Classic Scheil
- Scheil with back diffusion in the primary phase (more realistic for elements with high solid-state diffusivity)
- Scheil with solute trapping (for rapid solidification)
Practical use case: Predict microsegregation in a nickel superalloy casting to identify which minor phases form in the interdendritic regions. Or: calculate the solidification range of an aluminum casting alloy to assess hot tearing susceptibility.
6. Precipitation Simulations (TC-PRISMA Integration)
All precipitation calculations available in the Precipitation Module (TC-PRISMA) can be accessed through TC-Python. This is particularly powerful: you can run precipitation kinetics calculations as part of a larger automated workflow without manual GUI interaction.
What’s accessible:
- Nucleation kinetics (classical nucleation theory coupled with CALPHAD)
- Particle growth and coarsening
- Particle size distribution evolution during arbitrary heat treatment
- Multi-precipitate (multiple coexisting phases) simulation
- Driving force and critical nucleus calculations
Practical use case: Screen aging heat treatment temperatures for a nickel superalloy by running TC-PRISMA precipitation calculations at 50 different temperatures in a loop and identifying which gives the fastest γ’ nucleation rate or the target mean particle size after a given aging time.
7. Diffusion Simulations (DICTRA Integration)
Diffusion Module (DICTRA) calculations can be accessed through TC-Python, enabling automated diffusion simulation in coupling with other tools.
What’s accessible:
- Multicomponent diffusion in single-phase and multiphase regions
- Carburization and decarburization profiles
- Homogenization simulation
- Interdiffusion in diffusion couples
Practical use case: Calculate carburization depth profiles for a steel gear at different case-hardening temperatures and times in an automated batch to find the optimal process window.
8. Additive Manufacturing Module (AM Module) Calculations
AM Module calculations — melt pool thermal simulations for LPBF and EBM (the latter added in 2026a) — are accessible through TC-Python. This is noteworthy: some AM Module calculations are only available through TC-Python and not through the graphical interface.
Practical use case: Screen laser power/scan speed parameter combinations for a Ti-6Al-4V LPBF process by running melt pool calculations across a parameter grid in TC-Python.
9. Property Models (Steel, Nickel, Titanium Model Libraries)
Pre-built Property Models and custom Property Models created using the TC-Python API are accessible programmatically:
- Steel Model Library: Austenite fraction, martensite start temperature (Ms), bainite start temperature (Bs), driving forces for ferrite/pearlite/bainite transformation, stacking fault energy, SFE — for carbon and alloy steels
- Nickel Model Library: γ’ volume fraction, γ/γ’ misfit, antiphase boundary (APB) energy, creep resistance parameters — for nickel-based superalloys
- Titanium Model Library: Phase fractions and transformation temperatures for Ti alloys
- Noble Metal Alloys Model Library: Optical properties and color as a function of composition for Au-Ag-Cu and related systems
These models encapsulate physical metallurgy knowledge in addition to pure thermodynamics — returning engineering-relevant outputs directly rather than raw thermodynamic quantities.
Practical use case: Calculate martensite start temperature across a grid of carbon and chromium contents in a steel alloy design exercise using the Steel Model Library.
10. Custom Property Models
TC-Python allows you to write your own Property Models — Python functions that combine thermodynamic quantities from Thermo-Calc with your own physical models. If the built-in models don’t capture a property you need, you can create it.
The BatchEquilibriumCalculation Pattern — The Workhorse of High-Throughput Work
For most high-throughput alloy screening applications, the BatchEquilibriumCalculation is the right tool. It is dramatically faster than looping individual equilibrium calculations when each individual system is simple (single phase or few phases, fast convergence). A comparison from the official documentation: 100 individual equilibria in a ternary system vs. 10,000 batch equilibria for a single phase — the batch calculation with 100× more data points runs faster.
The general workflow pattern in TC-Python:
# Conceptual structure — not literal API syntax, illustrative only
# 1. Initialize Thermo-Calc with your database
with TCPython() as start:
# 2. Define your system: elements and database
system = start.select_database_and_elements("TCFE15", ["Fe", "Cr", "Ni", "C"])
# 3. Create a batch equilibrium calculation
batch_calc = (system
.get_system()
.with_batch_equilibrium_calculation()
.with_temperature(700 + 273.15) # K
.with_pressure(101325)) # Pa
# 4. Define what to calculate for each composition
for cr_content in composition_grid:
batch_calc.add_calculation_with_composition("Cr", cr_content)
# 5. Run all calculations at once
results = batch_calc.run()
# 6. Extract results and process with NumPy/Pandas
phase_fractions = results.get_values_of("NP(*)") # numpy array
The key insight: defining 10,000 calculation points and running them together is dramatically more efficient than 10,000 individual with blocks. The batch approach is how you do genuine high-throughput CALPHAD.
TC-Python and Machine Learning — The Growing Application
The intersection of CALPHAD calculations and machine learning is one of the most active areas in computational materials science. TC-Python is the primary bridge between Thermo-Calc databases and ML workflows.
Training data generation: Machine learning models for predicting alloy properties (tensile strength, corrosion resistance, oxidation resistance) need large, diverse training datasets. TC-Python generates thermodynamic descriptors — phase fractions at multiple temperatures, liquidus and solidus temperatures, driving forces for specific phases, Scheil solidification profiles — for thousands of compositions automatically. These become features for ML models.
Physics-informed ML: Some ML approaches use CALPHAD predictions as physics-based features or constraints. TC-Python provides the CALPHAD physics; scikit-learn, TensorFlow, or PyTorch provides the ML. The combination can outperform either approach alone.
Active learning for alloy design: Active learning workflows iteratively select new compositions to calculate based on model uncertainty, calculate CALPHAD properties for those compositions via TC-Python, update the ML model, and repeat — efficiently exploring large alloy spaces.
Integration with TensorFlow and PyTorch: TC-Python explicitly supports NumPy, SciPy, and TensorFlow as compatible numerical environments. This means you can feed TC-Python outputs directly into TensorFlow tensors for neural network training or prediction without format conversion.
Common Phase Names in TC-Python (New in 2026a)
Thermo-Calc 2026a introduced common phase names in the graphical interface. The same feature is available in TC-Python for plots and tables when using compatible databases. This means TC-Python scripts that generate plots or formatted output can now display “austenite” and “ferrite” rather than “FCC_A1” and “BCC_A2” in their outputs.
For programmatic phase identification (checking whether a specific phase is present), you still reference phases by their database names. The common names are a display/output feature.
TC-Python vs. Alternative Python CALPHAD Tools
Two other Python tools are worth knowing about for context:
pycalphad — An open-source Python library for CALPHAD calculations that reads Thermo-Calc .tdb database files. It is free and runs without a Thermo-Calc license. Its strengths are accessibility (anyone can use it), customizability (full source code), and integration with the open-source CALPHAD community’s database work. Its limitations: it does not use Thermo-Calc’s proprietary databases (TCFE, TCNI, TCAL, etc.), it lacks the kinetic modules (DICTRA, TC-PRISMA), and its numerical robustness in complex multicomponent systems is generally lower than Thermo-Calc’s optimized engine.
PanPython (CompuTherm Pandat) — Pandat’s Python SDK, providing similar functionality to TC-Python but accessing Pandat’s databases and modules. For groups with Pandat licenses, PanPython is the equivalent tool.
The key distinction: TC-Python with Thermo-Calc’s proprietary databases gives you access to TCFE15, TCNI, TCAL, and other databases that are the most extensively validated and most widely cited in the primary literature. For publication-grade research where database credibility matters, this is the principal reason to use TC-Python over free alternatives.
Getting Started: Prerequisites and Installation
Required:
- Thermo-Calc installed and licensed (TC-Python is an add-on — requires a separate license)
- At least one thermodynamic and properties database (e.g., TCFE for steels, TCNI for nickel alloys)
- Python 3.x (TC-Python documentation specifies compatible versions for each release; check the 2026a release notes for current compatibility)
Installation: TC-Python is installed through Thermo-Calc’s standard installation package. After installing Thermo-Calc, TC-Python is available as a Python package that can be imported. Detailed installation instructions are in the Thermo-Calc installation guide (available from Help → Manuals Folder in Thermo-Calc).
Documentation access:
- TC-Python has searchable online documentation generated directly from the program
- Access from within Thermo-Calc: Help → Manuals Folder → TC-Python folder → Index HTML
- Available at Thermo-Calc’s online support documentation
- Dozens of official example scripts cover all major calculation types
- Jupyter notebook workflows are fully supported
Learning the API: The official example scripts are the most practical starting point. Examples are organized by calculation type (equilibrium, phase diagram, Scheil, precipitation, diffusion, property models) and cover the complete API surface. The GitHub repository AixViPMaP/TC-Python_Examples provides community-contributed scripts beyond the official examples.
When TC-Python Is Not the Right Choice
TC-Python adds overhead relative to the graphical interface — you need to write and debug code, manage the Python environment, and understand the API. It is not always the right tool:
Use the Graphical Interface when:
- You’re doing exploratory work — “what does this alloy’s phase diagram look like?”
- You’re running a single calculation or a small number of calculations that would take longer to code than to click through
- You’re learning Thermo-Calc for the first time
- You need to inspect intermediate results interactively during a calculation
- You’re generating a plot for a single presentation or paper figure
Use TC-Python when:
- You need more than ~50 calculations of the same type with varying parameters
- You want reproducible, version-controlled calculations
- You need to integrate Thermo-Calc with other software (FEM codes, ML frameworks, optimization algorithms)
- You’re building a workflow that other team members will run repeatedly
- You need custom post-processing or non-standard visualization
TC-Python in the ICME Workflow
Integrated Computational Materials Engineering (ICME) connects multiple scales of simulation — from electronic structure (DFT) through thermodynamics (CALPHAD), diffusion and precipitation kinetics (DICTRA/TC-PRISMA), to microstructure evolution and ultimately mechanical properties. TC-Python is the integration point for CALPHAD in this chain.
A representative ICME workflow using TC-Python:
- Input: Alloy composition + processing conditions
- Thermo-Calc via TC-Python: Equilibrium phase fractions, thermodynamic driving forces, Scheil solidification profile
- TC-PRISMA via TC-Python: Precipitation kinetics during heat treatment — γ’ particle size distribution vs. aging time
- External microstructure model: Phase-field or dislocation density model using TC-Python thermodynamic outputs as inputs
- Property prediction: Hall-Petch and precipitation strengthening models using microstructure outputs
- Output: Predicted yield strength, creep resistance, fatigue life for the designed alloy and process
TC-Python is what allows steps 2 and 3 to run automatically inside a Python workflow that orchestrates all other steps.
Summary
TC-Python transforms Thermo-Calc from an interactive calculation tool into a programmable thermodynamic engine. For materials scientists doing high-throughput alloy screening, computational metallurgists integrating CALPHAD into ICME workflows, or data scientists building ML models with CALPHAD-generated features, it is the essential bridge between Thermo-Calc’s validated databases and Python’s scientific computing ecosystem.
The ability to run thousands of equilibrium calculations, precipitation simulations, and Scheil solidifications in automated loops — accessing the same TCFE, TCNI, and TCAL databases that underpin the most-cited computational materials science work in the literature — is what makes TC-Python worth the additional license cost for any group doing systematic computational alloy design.
For TC-Python and Thermo-Calc licensing assistance, contact via Telegram: t.me/DoCrackMe
Also see: Thermo-Calc 2026a — What’s New: Complete Release Overview | Thermo-Calc vs FactSage vs Pandat — CALPHAD Software Compared | Thermo-Calc DICTRA — Diffusion Simulation Complete Guide
