T19: Scripting precipitation calculations

This tutorial was tested on
MatCalc version 6.00 rel 0.051
license: free
database: mc_fe.tdb, mc_fe.ddb

The use of scripting to help ensure repeatability of calculations and to simplify repetitive operations has been introduced for the equilibrium calculations Tutorial 13. The present tutorial describes how scripting can be used for precipitation calculations.

Complimentary files

Click here to view the script for this tutorial


  • Setting up precipitation domains
  • Setting up precipitate phases
  • Scripting a complex heat-treatment
  • Modifying precipiation parameters during heat-treatment
  • Plotting using scripts

The example used here uses the already familiar Fe-Nb-C system and considers a heat-treatment of an initially well-annealed ferritic microstructure with no primary precipitates. Cementite is initially allowed to nucleate on dislocations, and NbC on grain boundaries. The microstructure is heated into the austenite phase stability region, held isothermally and then cooled quickly (quenched). On quenching, a martensitic transformation occurs. This is modelled in MatCalc by a modification of the ferrite precipitation domain to increase the dislocation density as well as the addition of subgrains as possible nucleation sites for the NbC phase. The system is then subjected to a tempering heat treatment consisting of heating, isothermal hold and cooling stages.

Setting up the system and thermodynamics

Start the script by with two lines to make sure the right module (the core module) is used, and to create a new workspace:

use-module core
new-workspace $ creates a new workspace 

The following code can be used to check that the correct version of MatCalc is being used. This is useful when scripts rely on functionality that is only available in newer versions of the software. The code send-dialog-string sends a message to the user in the form of a dialogue box, and stop-run-script prevents any further commands from being executed.

if (matcalc_version<6000000)
    send-dialog-string "MatCalc version must be 6.00.0000 or higher to run this script. Stopping."

Scripts should be well commented to ensure that they can be easily understood later. See Tutorial 13 for a reminder of how comments are inserted.

Some information on the physical situation to be modelled and the assumptions made can be inserted into the MatCalc workspace for future reference.

$ enter workspace info

@ set-workspace-info Script T19
@ set-workspace-info +Calculation of precipitation
@ set-workspace-info +in Fe-0.1C-0,7Nb wt.% system
@ set-workspace-info +during a complex heat treatment
@ set-workspace-info +with phases BCC_A2, FCC_A1 and CEMENTITE.

The thermodynamic setup is then carried out. Firstly, the database is chosen and the selements and phases are selected. The database is then read.

open-thermodyn-database mc_fe.tdb             
select-elements FE C NB VA                            
select-phases BCC_A2 FCC_A1 CEMENTITE                  

The composition is entered:

set-reference-element FE
enter-composition WP C=0.1  NB=0.7  

and an equilibrium is calculated, after setting automatic start values.

set-temperature-celsius 1000                           

Setting up the precipitation domains

We proceed by creating the precipitation domains. The calculation involves heat-treatment in both ferrite (BCC_A2) and austenite (FCC_A1) phase stability regions, so we start by creating these two domains.

create-precipitation-domain ferrite
create-precipitation-domain austenite 

We must then tell MatCalc with which matrix phases to associate these domains:

set-precipitation-parameter ferrite X BCC_A2
set-precipitation-parameter austenite X FCC_A1

Structural parameters are then defined for ferrite (note comments describing the meanings of the commands):

$ In S[t]ructure, [e]quilibrium)[d]islocation density set to 1e12
set-precipitation-parameter ferrite T D E 1e12
$ In S[t]ructure, [g]rain diameter set to 100e-6
set-precipitation-parameter ferrite T G 100e-6 
$ In S[t]ructure, [s]ubgrain diameter is set to 10e-6
set-precipitation-parameter ferrite T S 10e-6
$ In S[t]ructure, subgrain el[o]ngation factor set to 10
set-precipitation-parameter ferrite T O 10 

and for austenite. Note that for ferrite, parameters characterising the subgrains are included because subgrain boundaries will be used as nucleation sites later in the calculation. In austenite, this is not the case so the parameters for this domain are not relevant and need not be set.

$ In S[t]ructure, [e]quilibrium)[d]islocation density set to 1e12
set-precipitation-parameter austenite T D E 1e12
$ In S[t]ructure, [g]rain size section, the grain diameter is set to 100e-6
set-precipitation-parameter austenite T G 100e-6 

Setting up the precipitate phases

The next stage in the script is to set up the precipitates. Firstly, we need to create precipitate phases from the equilibrium phases.

create-new-phase CEMENTITE P
create-new-phase FCC_A1#01 P

Note that this latter phase is derived from the second FCC_A1 phase, FCC_A1#01, which is automatically generated by MatCalc, based on a command in the database, as a result of the presence of the MX carbonitride former, Nb, in the system.

The precipitate phase are initialised with 100 size classes each.

set-precipitation-parameter CEMENTITE_P0 C 100
set-precipitation-parameter FCC_A1#01_P0 C 100     

Then the nucleation sites are defined:

$ In the [n]ucleation section, the nucleation [s]ites are set to [d]islocations
set-precipitation-parameter CEMENTITE_P0 N S D
$ [G]rain boundaries are [n]ucleation [s]ites for NbC precipitate
set-precipitation-parameter FCC_A1#01_P0 N S G

The nucleus composition of the iron-rich cementite precipitate phase is set to para-equilibrium, and that of NbC is set to ortho-equilibrium.

$ In the [n]ucleation section, the nucleus [c]omposition is set to [p]ara-composition
set-precipitation-parameter CEMENTITE_P0 N C P
$ [O]rtho-[c]omposition for the NbC precipitate [n]uclei
set-precipitation-parameter FCC_A1#01_P0 N C O  

Finally, the mobility database is read in:

read-mobility-database mc_fe.ddb        


For an isothermal precipitation simulation, we would now simply need to set the temperature and time and start the simulation. This procedure is described briefly below. However, we will here instead look at how to use a script to create a heat-treatment.

The heat-treatment consists of two sections:

An austenitisation and quenching treatment consisting of:

  • heating from room temperature to the austenitisation temperature; since this heating step involves a phase transformation from ferrite to austenite, this must be specified in two stages - heating up to the transformation temperature with a ferrite precipitation domain, and then heating from the transformation temperature with an austenite precipitation domain.
  • an isothermal hold at the austenitisation temperature
  • quenching to room temperature; again, this is separated into two stages, the first of which has an austenite precipitation domain, and the second, a ferrite precipitation domain.

A tempering treatment consisting of:

  • heating from room temperature to the tempering temperature
  • an isothermal hold at the tempering temperature
  • cooling to room temperature

The tempering treatment is carried out entirely in the ferrite phase stability region, so no change of precipitation domain is necessary.

Start by creating a heat treatment sequence called sample_ht.

create-heat-treatment sample_ht 

Heat- or thermomechanical treatments can consist of different types of segments. In this tutorial, we will use two of these:

  • Type 1: this consists of an end temperature and a heating/cooling rate (use a negative sign to specify cooling)
  • Type 3: this consists of an end temperature and a time.

We saw in Tutorial 6 that it is possible to define our own variables. Here, we use this functionality to define a very general script consisting of an austenitisation and a tempering step.

set-variable-value f_a_temp 850 $ferrite-> austenite transformation temp. in C
set-variable-value a_f_temp 600 $austenite-> ferrite transformation temp. in C
set-variable-value aus_temp 1100 $austenitisation temp. in C
set-variable-value temp_temp 600 $tempering temp. in C
set-variable-value rate_heat_to_aus 1 $rate of heating to aus_temp in K/s
set-variable-value rate_cool_from_aus -10 $rate of cooling from aus_temp in K/s
set-variable-value rate_heat_to_temp 1 $rate of heating to temp_temp in K/s
set-variable-value rate_cool_from_temp -1 $rate of cooling from temp_temp in K/s
set-variable-value aus_time 3600 $austenitisation time in seconds
set-variable-value temp_time 7200 $tempering time in seconds

Austenitisation and quenching treatment

Start by adding the first segment, using the command

append-ht-segment sample_ht

Then specify the [s]tart temperature. The notation [.] means the current segment. It is also possible to refer to the segments by number.

edit-ht-segment sample_ht . S 20

This first segment consists of heating, at a rate rate_heat_to_aus up to the temperature f_a_temp at which the ferrite-austenite phase transformation takes place.

The parameters for the segment are thus set; the parameter set no.[1] is chosen with end temperature f_a_temp and heating rate rate_heat_to_aus K/s.

edit-ht-segment sample_ht . 1 f_a_temp rate_heat_to_aus

The precipitation [d]omain associated with this segment must now be set, as it is [n]ot inherited from any previous

edit-ht-segment sample_ht . D N ferrite

We then append a new segment to accommodate the remainder of the heating ramp to the austenitisation temperature.

append-ht-segment sample_ht 

This new segment now becomes the current segment, so we can modify its parameters using the [.] notation. Again, the parameter set [1] is chosen with end temperature aus_temp and the same heating rate, rate_heat_to_aus, as before.

edit-ht-segment sample_ht . 1 aus_temp rate_heat_to_aus

We also need to change the precipitation [d]omain, so that it is [n]ot inherited from the previous segment but is instead set to austenite:

edit-ht-segment sample_ht . D N austenite

The next stage is the isothermal hold. Add a new segment.

append-ht-segment sample_ht

The isothermal hold is specified using parameter set type [3], with end temperature aus_temp and hold time aus_time.

edit-ht-segment sample_ht . 3 aus_temp aus_time

The precipitation domain (austenite) is inhterited from the previous segment.

edit-ht-segment sample_ht . D Y 

We next add two segments for cooling down from the austenitisation domain to room temperature. Add a new segment for the austenite domain part. Set the segment type to [1] and set the end temperature to the austenite-ferrite transformation temperature a_f_temp and the cooling rate to rate_cool_from_aus. Set the segment to inherit the precipitation domain (austenite).

append-ht-segment sample_ht 
edit-ht-segment sample_ht . 1 a_f_temp rate_cool_from_aus 
edit-ht-segment sample_ht . D Y

Add a further new segment for the ferrite domain part. In this case, we again use type [1] and, this time, set the end temperature to 20 and the cooling rate, as before, to rate_cool_from_aus. This time, the precipitation domain is not inherited, but is instead set to ferrite.

append-ht-segment sample_ht
edit-ht-segment sample_ht . 1 20 rate_cool_from_aus    
edit-ht-segment sample_ht . D N ferrite

In addition, since this ferrite is now quenched martensite, we make some modifications to the properties of the precipitation domain. As we saw in Tutorial 17, pre- and post-segment scripts can be appended to segments of a thermomechanical treatment. The syntax for these scripts is illustrated by the following line of code, which sets the equilibrium dislocation density in the ferrite domain to 1e14:

edit-ht-segment sample_ht . O +set-precipitation-parameter ferrite T D E 1e14

The O here indicates a p[o]st-segment script; a p[r]e-segment script is instead indicated by the letter R in place of the O. The +-sign means that the following piece of script is added to any existing commands. An existing command can be removed by prepending a --sign.

Similarly, in the following line, the [n]ucleation [s]ites of FCC_A1#01_P0 are set to include [s]ubgrains as well as [g]rains.

edit-ht-segment sample_ht . O +set-precipitation-parameter FCC_A1#01_P0 N S GS

Tempering treatment

The structure of the tempering treatment is similar to that of the austenitisation treatment, but somewhat simpler, since no phase transformation needs to be considered.

The first part of this treatment is a heating segment with an end temperature of temp_temp and a heating rate of rate_heat_to_temp. The precipitation domain is inherited from the previous segment.

append-ht-segment sample_ht
edit-ht-segment sample_ht . 1 temp_temp rate_heat_to_temp 
edit-ht-segment sample_ht . D Y 

This is followed by an isothermal hold for temp_time at the tempering temperature temp_temp; the precipitation domain is inherited:

append-ht-segment sample_ht 
edit-ht-segment sample_ht . 3 temp_temp temp_time
edit-ht-segment sample_ht . D Y 	

Finally, a cooling segment returns the system to room temperature with a rate of rate_cool_from_temp. The precipitation domain is once more inherited.

append-ht-segment sample_ht
edit-ht-segment sample_ht . 1 20 rate_cool_from_temp  
edit-ht-segment sample_ht . D Y 


The final part of the setup before the calculation is run consists of setting up the plots. We will create four X-Y plots in a single plot window as well as a histogram of precipitate size distribution for each of the precipitate phases.

Start by creating a GUI window of type p1 (X-Y plot)

new-gui-window p1

Then set up the default x-axis so that it is used for all the plots in this windows, and has the properties specified below:

set-gui-window-property . S U Y                    $ Use default x-axis
set-gui-window-property . S T Time [h]             $ Default x-axis title
set-gui-window-property . S Y lin                  $ Linear scale
set-gui-window-property . S S 1e-10..              $ Scaling limit x-axis
set-gui-window-property . S F 1/3600               $ Multiplication factor s -> h

The first plot will contain the temperature profile as determined by the heat-treatment. The y-axis is labeelled accordingly.

set-plot-option . S N B T$C %s                     $ Temperature in Celsius
set-plot-option . A Y 1 T Temperature [°C]         $ y-axis title

The legend box is removed because it is not necessary when only one series is plotted:

set-plot-option . L N

A new plot is then created in the existing plot window [.] using the command:

create-new-plot X . 

This is set up to show the phase fractions of the two precipitate phases. The syntax %s here means that the MatCalc variables are used as-is without any modification. (See Tutorial 5)

set-plot-option . A Y 1 T Phase fraction     	  $ y-axis title
$ New series: fraction of cementite precipitate phase
set-plot-option . S N B F$CEMENTITE_P0 %s 
$ New series: fraction of NbC precipitate phase        
set-plot-option . S N B F$FCC_A1#01_P0 %s 

There are two series in this plot, so we label them. The two series here are referred to by number. The ordering number corresponds to the order in which they appear in the plot, not in the plot window, and begins at 0.

set-plot-option . S M 0 Cementite    $ Rename series -> "Cementite"
set-plot-option . S M 1 NbC          $ Rename series -> "NbC"

A further new plot is created, to plot the number density of precipitates. The series are renamed; note that the numbering starts at 0 again because we are now in a new plot.

create-new-plot X .
set-plot-option . A Y 1 T N<sub>ppt</sub> [m<sup>-3</sup>] $ y-axis title
set-plot-option . A Y 1 Y log                      $ Log scale on y-axis
set-plot-option . S N B NUM_PREC$CEMENTITE_P0 %s
set-plot-option . S N B NUM_PREC$FCC_A1#01_P0 %s 
set-plot-option . S M 0 Cementite    $ Rename series in plot -> "Cementite"
set-plot-option . S M 1 NbC          $ Rename series in plot -> "NbC"

The final of the four plots shows the mean precipitate radius.

create-new-plot X .
$ Plotting the mean radius 
set-plot-option . A Y 1 T R<sub>mean</sub> [m]     $ y-axis title
set-plot-option . A Y 1 Y log                      $ Logarithmic scale on y-axis
set-plot-option 4 S N B R_MEAN$CEMENTITE_P0 %s     
set-plot-option 4 S N B R_MEAN$FCC_A1#01_P0 %s  
set-plot-option 4 S M 0 Cementite    $ Rename series in plot -> "Cementite"
set-plot-option 4 S M 1 NbC          $ Rename series in plot --> "NbC"

Major gridlines are switched on for both x- and y-axes of all plots. Here the plots are referred to their number, starting from 1.

set-plot-option 1 G M X Y 
set-plot-option 1 G M Y Y  
set-plot-option 2 G M X Y   
set-plot-option 2 G M Y Y     
set-plot-option 3 G M X Y        
set-plot-option 3 G M Y Y     
set-plot-option 4 G M X Y      
set-plot-option 4 G M Y Y     

The plots are arranged so that they occupy two columns:

set-gui-window-property . N 2

A new GUI window of type p5 is created for the first histogram:

new-gui-window p5  

The default x-axis is set up, with the scaling factor used to give plotting in nanometres rather than metres.

set-gui-window-property . S U Y                    		
set-gui-window-property . S T Precipitate radius [nm] $ x-axis title
set-gui-window-property . S F 1e9                     $ Multiplication [f]actor

A [n]ew [s]eries showing the [p]recipitate distribution of the “cementite_p0” phase is plotted:

set-plot-option . S N P CEMENTITE_P0

Options controlling the histogram are then set.

set-plot-option . H N 20 $ [n]umber of [h]istogram classes set to 20
set-plot-option . T Cementite precipitate distribution    $ plot title
set-plot-option . A Y 1 T Number density of precipitates  [m<sup>-3</sup>]  
set-plot-option . L N                                     $ [N]o legend box

The second histogram, for NbC precipitates, is set up similarly.

new-gui-window p5
set-gui-window-property . S U Y                          $ Use default x-axis
set-gui-window-property . S T Precipitate radius [nm]    $ x-axis title
set-gui-window-property . S F 1e9                $ Multiplication [f]actor

set-plot-option . S N P FCC_A1#01_P0
set-plot-option . H N 20                                  $ number of classes
set-plot-option . T NbC precipitate distribution          $ plot title
set-plot-option . A Y 1 T Number density of precipitates  [m<sup>-3</sup>]  
set-plot-option . L N     

Running the calculation

We first save the workspace setup as it before the calculation. This enables us to easily revert to this pre-calculation state if necessary.

save-workspace Tutorial_19_setup

An isothermal calculation can be carried out as follows. This can be useful as a preliminary calculation to check that everything is working.

An end-time for the simulation is first set:

set-simulation-parameter E 7200  $ Simulation end tim[e] in s 

Then, the temperature control of the simulation is set to be [I]sothermal and the required temperature specified.

set-simulation-parameter T I 600

A further line is added to specify that this temperature is in Celsius.

set-simulation-parameter P Y           $ Tem[p]erature in Celsius

The calculation can then be executed using:


When this has been successfully carried out, the line specifying isothermal temperature control should be commented out by prepending a dollar sign so that it looks as shown:

$set-simulation-parameter T I 600

The temperature control is instead set to be governed by the [h]eat treatment “sample_ht” with a maximum temperature step of 10:

set-simulation-parameter T H sample_ht 10

Again, the simulation is started using:


When the calculation is over, the workspace can be saved using:

save-workspace Tutorial_19

In addition, we can export whole frames or individual plots:

export-frame-to-file 2 N frame.png
export-frame-to-file 3 N T19_histo_cementite.png
export-plot-to-file 4 N T19_Rmean 

The x-y plot window should look as follows after the calculation:

T19 xy plots

Subsequent articles

The tutorial is continued in Tutorial 20 - Simulating grain growth

Go to the MatCalc tutorial index.

tutorials/t19.txt · Last modified: 2018/06/13 19:43 (external edit)