This tutorial was tested on
MatCalc version 6.03 rel 1.000
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.

Click here to view the (slightly reordered) 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.

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 

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."
    stop-run-script
endif

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-thermodynamic-database mc_fe.tdb             
select-elements FE C NB VA                            
select-phases BCC_A2 FCC_A1 CEMENTITE                  
read-thermodynamic-database

Also, the mobility database is read in:

read-mobility-database mc_fe.ddb        

The composition is entered:

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

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

set-automatic-startvalues
set-temperature-celsius 1000                           
calculate-equilibrium                                 

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 thermodynamic-matrix-phase=BCC_A2
set-precipitation-parameter austenite thermodynamic-matrix-phase=FCC_A1

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

set-precipitation-parameter ferrite equilibrium-dislocation-density=1e12
set-precipitation-parameter ferrite initial-grain-diameter=100e-6 
set-precipitation-parameter ferrite initial-subgrain-diameter=10e-6
set-precipitation-parameter ferrite subgrain-elongation-factor=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.

set-precipitation-parameter austenite equilibrium-dislocation-density=1e12
set-precipitation-parameter austenite initial-grain-diameter=100e-6 

The next stage in the script is to set up the precipitates. Firstly, we need to create precipitate phases from the equilibrium phases. As two nucleation sites are to be used for FCC_A1#01-precipitates, two precipitate phases are created.

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

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 number-of-size-classes=100
set-precipitation-parameter FCC_A1#01_P0 number-of-size-classes=100
set-precipitation-parameter FCC_A1#01_P1 number-of-size-classes=100     

Then the nucleation sites are defined:

set-precipitation-parameter CEMENTITE_P0 nucleation-sites=dislocations
set-precipitation-parameter FCC_A1#01_P0 nucleation-sites=grain-boundaries
set-precipitation-parameter FCC_A1#01_P1 nucleation-sites=none

The nucleation sites for FCC_A1#01_P1 phase are set to 'none', so that this phase is not going to appear at the start of the simulation. However, this setting will be changed in the heat treatment setup.
The nucleus composition of the iron-rich cementite precipitate phase is set to para-equilibrium, and that of NbC is set to ortho-equilibrium.

set-precipitation-parameter CEMENTITE_P0 nucleus-composition-model=para-composition
set-precipitation-parameter FCC_A1#01_P0 nucleus-composition-model=ortho-composition
set-precipitation-parameter FCC_A1#01_P1 nucleus-composition-model=ortho-composition 

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-tm-treatment sample_ht 

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

• Definition with segment end temperature and a heating/cooling rate
• Definition with segment end temperature and a duration 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

Start by adding the first segment, using the command

append-tmt-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-tmt-segment sample_ht . segment-start-temperature=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.

edit-tmt-segment sample_ht . T_end+T_dot f_a_temp rate_heat_to_aus

The precipitation domain associated with this segment must now be set.

edit-tmt-segment sample_ht . precipitation-domain=ferrite

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

append-tmt-segment sample_ht 

This new segment now becomes the current segment, so we can modify its parameters using the [.] notation. The end temperature aus_temp and the same heating rate as before, rate_heat_to_aus, are chosen.

edit-tmt-segment sample_ht . T_end+T_dot aus_temp rate_heat_to_aus

We also need to change the precipitation domain to austenite:

edit-tmt-segment sample_ht . precipitation-domain=austenite

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

append-tmt-segment sample_ht

The isothermal hold is specified with end temperature aus_temp and hold time aus_time.

edit-tmt-segment sample_ht . T_end+delta_t aus_temp aus_time

The precipitation domain remains austenite.

edit-tmt-segment sample_ht . precipitation-domain=austenite 

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 end temperature to the austenite-ferrite transformation temperature a_f_temp and the cooling rate to rate_cool_from_aus. Set the precipitation domain to austenite.

append-tmt-segment sample_ht 
edit-tmt-segment sample_ht . T_end+T_dot a_f_temp rate_cool_from_aus 
edit-tmt-segment sample_ht . precipitation-domain=austenite

Add a further new segment for the ferrite domain part. In this case, we set the end temperature to 20 and the cooling rate, as before, to rate_cool_from_aus. This time, the precipitation domain is set to ferrite.

append-tmt-segment sample_ht
edit-tmt-segment sample_ht . T_end+T_dot 20 rate_cool_from_aus    
edit-tmt-segment sample_ht . precipitation-domain=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-tmt-segment sample_ht . pre-segment-command=set-precipitation-parameter ferrite equilibrium-dislocation-density=1e14

Similarly, in the following line, the nucleation sites of FCC_A1#01_P1 are set to subgrains, replacing the previous 'none' setting. 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.

edit-tmt-segment sample_ht . pre-segment-command=+set-precipitation-parameter FCC_A1#01_p1 nucleation-sites=subgrain-boundaries 

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 left the same as in the previous segment.

append-tmt-segment sample_ht
edit-tmt-segment sample_ht . T_end+T_dot temp_temp rate_heat_to_temp
edit-tmt-segment sample_ht . precipitation-domain=ferrite 

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

append-tmt-segment sample_ht 
edit-tmt-segment sample_ht . T_end+delta_t temp_temp temp_time
edit-tmt-segment sample_ht . precipitation-domain=ferrite

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

append-tmt-segment sample_ht
edit-tmt-segment sample_ht . T_end+T_dot 20 rate_cool_from_temp
edit-tmt-segment sample_ht . precipitation-domain=ferrite 

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 . default-x-axis-for-all-plots=yes 
set-gui-window-property . default-x-axis-title=Time [h]
set-gui-window-property . default-x-axis-type=lin 
set-gui-window-property . default-x-axis-factor=1/3600

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

set-plot-option . series new buffer t$c
set-plot-option . y-axis-title=Temperature [°C]

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

set-plot-option . legend-alignment=none

Major gridlines are switched on for both x- and y-axes.

set-plot-option . grid major enable-x-axis=yes 
set-plot-option . grid major enable-y-axis=yes

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

create-new-plot xy-plot . 

This is set up to show the phase fractions of the two precipitate phases. (See Tutorial 5)

set-plot-option . y-axis-title=Phase fraction
set-plot-option . grid major enable-x-axis=yes 
set-plot-option . grid major enable-y-axis=yes 
set-plot-option . series new buffer f$cementite_p0
set-plot-option . series new buffer f$fcc_a1#01_p0
set-plot-option . series new buffer f$fcc_a1#01_p1

There are three series in this plot, so we label them. The three 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 . series rename 0 Cementite
set-plot-option . series rename 1 NbC(gb)
set-plot-option . series rename 2 NbC(sgb)

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 xy-plot . 
set-plot-option . y-axis-title=N<sub>ppt</sub> [m<sup>-3</sup>]
set-plot-option . y-axis-type=log 
set-plot-option . grid major enable-x-axis=yes 
set-plot-option . grid major enable-y-axis=yes 
set-plot-option . series new buffer num_prec$cementite_p0
set-plot-option . series new buffer num_prec$fcc_a1#01_p0
set-plot-option . series new buffer num_prec$fcc_a1#01_p1
set-plot-option . series rename 0 Cementite
set-plot-option . series rename 1 NbC(gb)
set-plot-option . series rename 2 NbC(sgb)

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

create-new-plot xy-plot . 
set-plot-option . y-axis-title=R<sub>mean</sub> [m]
set-plot-option . y-axis-type=log 
set-plot-option . grid major enable-x-axis=yes 
set-plot-option . grid major enable-y-axis=yes 
set-plot-option . series new buffer r_mean$cementite_p0
set-plot-option . series new buffer r_mean$fcc_a1#01_p0
set-plot-option . series new buffer r_mean$fcc_a1#01_p1
set-plot-option . series rename 0 Cementite
set-plot-option . series rename 1 NbC(gb)
set-plot-option . series rename 2 NbC(sgb)

The plots are arranged so that they occupy two columns:

set-gui-window-property . number-of-plot-columns=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 . default-x-axis-for-all-plots=yes 
set-gui-window-property . default-x-axis-title=Precipitate radius [nm]
set-gui-window-property . default-x-axis-factor=1e9

Options controlling the histogram are then set.

set-plot-option . number-of-size-classes=20
set-plot-option . plot-title=Precipitate distributions
set-plot-option . y-axis-title=Number density of precipitates [m<sup>-3</sup>]

New series showing the precipitate distribution of the precipitate phases are plotted:

set-plot-option . series new precipitate-distribution CEMENTITE_P0 
set-plot-option . series new precipitate-distribution FCC_A1#01_P0 
set-plot-option . series new precipitate-distribution FCC_A1#01_P1

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 (in seconds) for the simulation is first set:

set-simulation-parameter end-time=7200

Then, the temperature control of the simulation is set to be isothermal and the required temperature specified.

set-simulation-parameter isothermal-temperature=600

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

set-simulation-parameter temperature-in-C=yes

The calculation can then be executed using:

start-precipitate-simulation

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 isothermal-temperature=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 tm-treatment-name=sample_ht

Again, the simulation is started using:

start-precipitate-simulation

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 png t19_xy_plots
export-frame-to-file 3 png t19_histo_cementite
export-plot-to-file 4 png t19_r_mean 

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

The tutorial is continued in Tutorial 20 - Simulating grain growth

Go to the MatCalc tutorial index.