T13: Introduction
to scripting (1: Equilibrium calculations)
This tutorial was created on
MatCalc version 5.23 rel 1.026
license: free
database: mc_sample_fe.tdb
Contents:
- Purpose of scripts
- Writing a script to perform a stepped calculation and display
the results
1. Introduction
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 (see the examples of those in Application section).
Writing a script
There are two ways of creating a script:
1. In MatCalc, choose 'New' from
the 'File' menu and select 'Text
file' from the drop-box. Note that it is possible to have
any number of text files open simultaneously with a MatCalc workspace
file.
'Save' or 'Save
as' will save the text file if its window is highlighted,
otherwise the workspace will be saved. Recently used text 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!
Reading a script
There are three ways of loading a script:
1. Using 'File > Open' or clicking on icon in the toolbar (keyboard shortcut 'Ctrl + O'). Select the filter to 'MatCalc script (*.mcs)' files
2. Using 'Extra > Run script' or clicking on icon in the toolbar (keyboard shortcut 'Shift + F2')
3. Double-clicking on the '.mcs' file icon
2. 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.
Comments
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.1
$ 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
@$************************************
open_thermodyn_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_sample_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 fcc cem
@$************************************
$ read in the thermodynamic data
@$************************************
read_thermodyn_database
@$************************************
$ enter the composition
@$************************************
enter_composition wp c=0.4
@$************************************
$ set the temperature and calculate an equilibrium
@$************************************
set_temperature_celsius 700
set_automatic_startvalues
calculate_equilibrium
Stepped calculation
In the line below, the argument 'r' means
range, and the numerical values are the start, end and step interval.
@$************************************
$ define step parameters and make stepped calculation
@$************************************
set_step_option r 400 1600 L 25
step-equilibrium
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 . x t$c
set_gui_window_property . s u y $ set default x-axis to be used
for all plots
set_gui_window_property . s t Temperature [°C] $ title for
default x-axis
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 . t 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 . a y 1 t Phase fraction [%]
set-plot-option . a y 1 f 100
set-plot-option . a y 1 y log $
changes axis type to log
set-plot-option . a y 1 s 1..100 $
modifies axis scaling
The first series is inserted using 'set-plot-option
. s n b f$liquid';
this is the phase fraction of liquid. The name of the series, as
it will appear on the legend, is then edited using 'set-plot-option
. s m -1 f$liquid Liquid'. This changes the name from its automatic
value (f$liquid) to 'Liquid'.
set-plot-option . s n b f$liquid
set-plot-option . s m -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 . s n b f$bcc_a2
set-plot-option . s m -1 f$bcc_a2 Ferrite
set-plot-option . s n b f$fcc_a1
set-plot-option . s m -1 f$fcc_a1 Austenite
set-plot-option . s n b f$cementite
set-plot-option . s m -1 f$cementite Fe<sub>3</sub>C
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 . 20 20 800 1000
update-gui-window .
set_gui_window_property . y col_no_symb $sets style-sheet
to colour with no symbols.
Another plot can be added in the current window as shown below
create_new_plot x .
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 . t Composition of phases
set-plot-option . a y 1 t Carbon content [wt.%] $ label on y-axis
set-plot-option . s n b x$liquid$C wp $ adding the first series...
set-plot-option . s m -1 x$liquid$C Liquid $... and changing its
name.
set-plot-option . s n b x$bcc_a2$C wp
set-plot-option . s m -1 x$bcc_a2$C Ferrite
set-plot-option . s n b x$fcc_a1$C wp
set-plot-option . s m -1 x$fcc_a1$C Austenite
set-plot-option . s n b x$cementite$C wp
set-plot-option . s m -1 x$cementite$C Fe<sub>3</sub>C
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 script 'T13.mcs' can be found in the 'download' folder.
The final diagrams should look like this:


|