T13: Introduction to scripting - Equilibrium calculations

This tutorial was tested on
MatCalc version 6.03 rel 1.000
license: free
database: mc_fe.tdb

Complimentary files

Click here to view the script for this tutorial


  • Purpose of scripts
  • Writing a script to perform a stepped calculation and display the results


Utility of scripts

A script is a text file, containing a list of commands to be executed in order from top to bottom. They are particularly useful to speed up routine or repetitive operations. Once a script file has been created, it can easily be modified to serve a new purpose, for example by changing the elements or phases in the system. Script files, consisting only of text, are also much smaller in size than MatCalc workspace files, especially those resulting from precipitation calculations.
Individual scripts can also be grouped into master-scripts; this facilitates, for example, calculations involving multi-stage heat treatments. Some sample scripts are provided with MatCalc. You will find them in the subdirectories of 'MatCalc/scripts/script_menu/templates'. Of course, you can also edit them in MatCalc by clicking on 'Open template…' in 'Script' menu.

Creating a script

There are two ways of creating a script:

  1. In MatCalc, choose 'New' from the 'File' menu and select 'Script file' from the drop-box. Note that it is possible to have any number of script files open simultaneously with a MatCalc workspace file. 'Save' or 'Save as' will save the script file if its window is highlighted, otherwise the workspace will be saved. Recently used script files can be found in a list under 'File → Recent files'.
  2. Alternatively, create the new script in any text editor (which saves files as plain text), such as notepad, emacs, vi or any of the many text editors available in different Linux distributions.

N.B.- The MatCalc scripts have '.mcs' extension so it is important to set (or change) the extension of the created file!

Writing a script

The scripts are written by typing in the commands used in the console. Similar as in the console, a suggester functionality is present in the script window which improves the script writing process. Each line might contain only one command. Empty lines will improve the readability of the script file in an editor, otherwise these do not influence the execution of the script. A '$'-sign that is not a part of the command (i.e. there is at least one blank space between the command and the '$' -sign) is interpreted as a beginning of the comment, so that everything that follows the '$' within this line will be ignored during script execution. The comments can be introduced both in separate lines and in the lines containing the MatCalc commands. In the latter case, the comment is to be put after a command. To mark many lines as a comment, a '$$'-sign can be used at the beginning and the end of the commented text.

Editing a script

There are also two ways of editing an existing script:

  1. In MatCalc, using 'File → Open' or clicking on  MatCalc icon icon in the toolbar (keyboard shortcut 'Ctrl + O'). Select the filter to 'MatCalc script (*.mcs)' files
  2. Alternatively, you can use any text editor (which saves files as plain text).

Executing a script

And again, there are two ways of executing a script in MatCalc:

  1. Using 'Script → Run script' or clicking on  MatCalc icon icon in the toolbar (keyboard shortcut 'Shift + F2')
  2. Double-clicking on the '.mcs' file icon

Example: a stepped equilibrium

This example will show how to write a script to perform the stepped calculation in Tutorial 3 and display the results.


It is always advisable to comment the script extensively so as to help other users (or oneself several months later!) to understand the aim of the calculation, assumptions, etc. Any line prefixed with a '$'-sign will not be interpreted as a command. The '$'-sign can also be inserted part-way through a line; the rest of the line will be treated as a comment.

$ This whole line is a comment.
new-workspace   $ The rest of this line is a comment.

Both comments and commands are shown line-by-line in the console when the script is executed, but prefixing a comment or a command with the '@'-sign hides the line so that it does not appear in the console output.
At the beginning of the script, enter some preliminary comments, containing such information as: the name of the file, the current version of MatCalc (available from Help > About), the current version of the scripting language and a brief summary of the purpose of the script.

$ Script T13
$ This is a script for MatCalc version 5.41
$ MatCalc script version 1 
$ Calculating equilibrium phase stability in Fe-0.4C wt.%

Save the file as 'T13.mcs'

Calculating an equilibrium

The first executable line in the script creates a new workspace (N.B.- Any previously open workspace will be closed without warning.)

$ Create a new workspace file
new-workspace $this executes 'autonew.mcs' script

The next lines are to enter some workspace information to describe the ideas, assumptions etc. used in the calculation. This information can be found in 'File > Workspace info'. The '+'-sign continues the text on a new line.

$ enter workspace info
@ set-workspace-info Script T13
@ set-workspace-info +Calculation of equilibrium phase stability
@ set-workspace-info +in Fe-0.4C wt.% system
@ set-workspace-info +with phases LIQUID, BCC_A2, FCC_A1 and CEMENTITE.

Next, add the command-line to open the thermodynamic database.

$ open the thermodynamic database

If the line is put in as above, the script will stop at this point and prompt the user for the name of a thermodynamic database. The output in the console window is as follows:

<script(0)> $ open the thermodynamic database
<script(0)> open_thermodyn_database
name for thermodynamic database /mc_sample_fe/:

(Press 'enter' to select the default option.) Leaving out the arguments of the command in this way allows for interactivity in scripts. If, instead, the script is intended to be fully automatic, the argument should be put after the command on the same line. Replace the above line with the following:

open-thermodyn-database mc_fe.tdb

The next parts of the script are to set up the system, set the temperature and calculate an equilibrium. These commands have already been seen in Tutorial 12.

$ select elements and phases
select-elements c fe
select-phases liq bcc_a2 fcc cem
$ read in the thermodynamic data
$ enter the composition
enter-composition weight-percent c=0.4
$ set the temperature and calculate an equilibrium
set_temperature_celsius 700

Stepped calculation

In the line below, after the argument 'range', the numerical values are the start, end, step type (linear) and step interval.
$ define step parameters and make stepped calculation
set-step-option range 400 1600 lin 25

Graphical output

The final part of the script is concerned with graphical presentation of results. The following line creates a new GUI window to contain the plot. As was seen in Tutorial 12, the code 'p1' is used to open an XY-plot.

$ graphical output
new-gui-window p1

The following three lines change the default x-data from 'StepValue' to temperature in Celsius, set a default x-axis to be used for all plots, and provide a title for this axis. The '.' in these lines refers to the ID of the last-used window, which in this case is the p1 window which has just been created.

set-gui-window-property . default-x-axis-data=t$c
set-gui-window-property . default-x-axis-for-all-plots=yes
set-gui-window-property . default-x-axis-title=Temperature [°C]

The line below adds a title to the diagram. This first diagram is to be a plot of phase fraction versus temperature.

set-plot-option . plot-title=Phase stability in Fe-0.4 wt.% C

The following lines label the y-axis, change the 'factor' of the y-axis from 1 to 100 to display the calculated phase fraction directly in percent, set the axis type to logarithmic and modify the axis scaling.

set-plot-option . y-axis-title=Phase fraction [%]
set-plot-option . y-axis-factor=100
set-plot-option . y-axis-type=log
set-plot-option . y-axis-scaling=1..100

Next, the first series 'f$liquid' is inserted; this is the phase fraction of liquid. The name of the series, as it will appear on the legend, is then edited, changing the name from its automatic value (f$liquid) to 'Liquid'.

set-plot-option . series new buffer f$liquid
set-plot-option . series rename -1 f$liquid Liquid

These commands are repeated for the other phases. Note the use of the HTML markup tags to give the subscript in 'Fe3C'.

set-plot-option . series new buffer f$bcc_a2
set-plot-option . series rename -1 f$bcc_a2 Ferrite
set-plot-option . series new buffer f$fcc_a1
set-plot-option . series rename -1 f$fcc_a1 Austenite
set-plot-option . series new buffer f$cementite
set-plot-option . series rename -1 f$cementite Fe<sub>3</sub>C

The major grid lines for x- and y-axis are displayed by these commands:

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

The three lines below move and resize the window, update its contents and set the style-sheet to coloured with no symbols. In the first of these lines, the first two numbers define the position of the window, the second two define the width and height.

move-gui-window displace . 20 20 800 1000
update-gui-window .
set-gui-window-property . style-sheet=col_no_symb

Another plot can be added in the current window as shown below

create-new-plot xy-plot .

The newly created plot now becomes the 'current' plot and can be referred to as '.' when it is being modified with set_plot_option:

set-plot-option . plot-title=Composition of phases
set-plot-option . y-axis-title=Carbon content [wt.%]
set-plot-option . series new buffer x$liquid$c$wp
set-plot-option . series rename -1 x$liquid$c$wp Liquid
set-plot-option . series new buffer x$bcc_a2$c$wp
set-plot-option . series rename -1 x$bcc_a2$c$wp Ferrite
set-plot-option . series new buffer x$fcc_a1$c$wp
set-plot-option . series rename -1 x$fcc_a1$c$wp Austenite
set-plot-option . series new buffer x$cementite$c$wp
set-plot-option . series rename -1 x$cementite$c$wp Fe<sub>3</sub>C
set-plot-option . grid major enable-x-axis=yes
set-plot-option . grid major enable-y-axis=yes

The script can be concluded with the following line, which should appear in the console when the script has been executed without any errors.

$ *** DONE ***

The final diagrams should look like this:

 MatCalc plot

 MatCalc plot

Consecutive articles

tutorials/t13.txt · Last modified: 2023/08/02 20:56 by
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki