Understanding the TC-Python Module : A Beginner’s Scripting Guide

If you are a materials scientist, you know the feeling: you need to map out 500 different alloy compositions, which means clicking through the Thermo-Calc graphical interface 500 times. It’s tedious, prone to human error, and a massive waste of expensive research time.

Enter TC-Python.

TC-Python is the official Application Programming Interface (API) for Thermo-Calc. It acts as a bridge between Python—the world’s most popular programming language—and Thermo-Calc’s powerful thermodynamic calculation engine. In this beginner’s guide, we will break down what TC-Python is, why you need it, and how to write your very first automation script.

Note: To follow this guide, you will need Thermo-Calc 2026 and its corresponding Python module installed. If you need the software, you can download Thermo-Calc 2026 here.

Why Should Materials Scientists Learn TC-Python?

You don’t need to be a software developer to use TC-Python. If you can copy and paste, you can automate your workflows. Here is why it’s worth the effort to learn:

• High-Throughput Screening: Easily loop through thousands of compositions (like High-Entropy Alloys) or temperature ranges in seconds.
• Data Export Made Easy: Instead of manually copying data from Thermo-Calc into Excel, TC-Python can automatically export your results directly into CSV, JSON, or pandas dataframes.
• Integration with Machine Learning: Python is the language of AI. You can use TC-Python to generate massive training datasets of phase diagrams to feed into machine learning models for materials discovery.
• Custom Calculations: Create complex, multi-step calculations (e.g., “find the exact temperature where this specific phase reaches 5% fraction”) that are impossible to do in the standard GUI.

Step 1: Setting Up Your Environment

Before writing code, ensure you have Python installed on your computer (version 3.8 or newer is recommended). Thermo-Calc 2026 makes installation easy.

1. Open your command prompt (Windows) or terminal (Mac/Linux).
2. Type the following command and press Enter:
   pip install tc_python
3. Once installed, you can open any Python IDE (like VS Code, PyCharm, or Jupyter Notebook) and start scripting.

Step 2: The Anatomy of a TC-Python Script

Every TC-Python script follows a simple, logical 5-step workflow. No matter how complex your calculation becomes, it will always follow this skeleton:

1. Initialize: Start the Thermo-Calc engine.
2. Select Database: Load your thermodynamic database (e.g., TCFE for steels).
3. Define Elements: Tell the software which elements are in your system.
4. Set Conditions: Input temperature, pressure, and composition.
5. Calculate & Extract: Run the math and pull out the specific numbers you want.

Step 3: Your First Script (Calculating Phase Fractions)

Let’s write a real script. We are going to calculate the equilibrium phase fractions of a low-carbon steel (Fe-0.1wt%C) at 1000°C.

Copy and paste this code into your Python editor and run it:

# 1. Import the TC-Python module
from tc_python import TCpython

# 2. Initialize the Thermo-Calc engine
with TCpython() as tcp:
    
    # 3. Select the database and elements
    # (FEDEMO is a default demo database, swap this for TCFE, TCHEA, etc.)
    tcp.set_database_and_elements("FEDEMO.TDB", ["Fe", "C"])
    
    # 4. Set the conditions
    tcp.set_condition("T", 1000)           # Temperature in Celsius
    tcp.set_condition("P", 101325)         # Pressure in Pascal (1 atm)
    tcp.set_composition("C", 0.1, "wt%")  # 0.1 weight percent Carbon
    tcp.set_composition("Fe", 99.9, "wt%")# Balance Iron
    
    # 5. Calculate equilibrium
    result = tcp.calculate()
    
    # 6. Extract and print the data
    print("--- Calculation Successful ---")
    print(f"Temperature: {result.get_value('T')} C")
    
    # Loop through all stable phases and print their fractions
    phases = result.get_phases_in_system()
    for phase in phases:
        phase_name = phase.get_phase_name()
        phase_frac = phase.get_fraction_of_phase()
        
        # Only print phases that actually exist (fraction > 0)
        if phase_frac > 0:
            print(f"Phase: {phase_name} | Fraction: {phase_frac:.4f}")
            
print("Script finished.")

What to expect when you run this:
Your terminal will output something like:

--- Calculation Successful ---
Temperature: 1000.0 C
Phase: FCC_A1 | Fraction: 1.0000
Script finished.

Step 4: Taking it to the Next Level (Adding a Loop)

The real power of TC-Python happens when you add a simple Python for loop. Let’s modify the script above to see how the phase fractions change as we increase the Carbon content from 0.1% to 1.0%.

Replace Step 4 and 5 in your script with this:

    # Create a loop for different carbon contents
    for carbon_content in [0.1, 0.2, 0.4, 0.6, 0.8, 1.0]:
        
        # Reset conditions for this specific loop iteration
        tcp.reset_conditions()
        tcp.set_condition("T", 1000)
        tcp.set_condition("P", 101325)
        tcp.set_composition("C", carbon_content, "wt%")
        tcp.set_composition("Fe", 100.0 - carbon_content, "wt%")
        
        # Calculate
        result = tcp.calculate()
        
        # Print results nicely
        print(f"At {carbon_content}% C:", end=" ")
        phases = result.get_phases_in_system()
        
        # Get a list of existing phases for this composition
        existing_phases = [p.get_phase_name() for p in phases if p.get_fraction_of_phase() > 0]
        print(" | ".join(existing_phases))

With just 5 extra lines of code, you’ve completely automated what would have taken 10 minutes of clicking in the Thermo-Calc GUI.

Where to Go From Here?

Once you are comfortable with this basic structure, you can start exploring the massive TC-Python documentation to learn how to:

• Map binary and ternary phase diagrams programmatically.
• Run Scheil simulations via script.
• Save your results directly to a .csv file using Python’s built-in csv module.

Don’t be intimidated by programming. Think of Python simply as a remote control for Thermo-Calc. Once you learn the buttons, you can run your simulations on autopilot.

Ready to Automate Your Research?

You need the latest version of the software to ensure full compatibility with modern Python libraries. Download Thermo-Calc 2026 here and start scripting today.