T12: Using
the MatCalc console
This tutorial was created on
MatCalc version 5.23 rel 1.026
license: free
database: mc_sample_fe.tdb
Contents:
- Getting help in the MatCalc console
- Obtaining lists of available commands for different modules
- Command syntax and abbreviations
- Example: calculating an equilibrium using the command-line
- Evaluating numerical expressions and variables
- Defining, using and plotting functions
1. Basics
Getting help and listing available commands
Typing '?' or 'HELP_WORKSPACE' in the console window shows a list
of available commands.
_mcore: ?
-------------------------------------------------------------------------------
available commands in workspace module:
-------------------------------------------------------------------------------
? |
HELP_WORKSPACE |
HELP_CORE_MODULE |
HELP_SIMULATION_MODULE |
HELP_MONTECARLO_MODULE |
ECHO |
! |
EXIT |
USE_MODULE |
BACK_TO_MODULE |
NEW_WORKSPACE |
READ_WORKSPACE |
SAVE_WORKSPACE |
CLOSE_WORKSPACE |
SET_WORKSPACE_PROPERTY |
SET_WORKSPACE_INFO |
LIST_WORKSPACE_INFO |
RUN_SCRIPT_FILE |
NEW_GUI_WINDOW |
REMOVE_GUI_WINDOW |
MOVE_GUI_WINDOW |
SET_GUI_WINDOW_PROPERTY |
UPDATE_GUI_WINDOWS |
LIST_GUI_WINDOW_PROPS |
LIST_ALL_GUI_WINDOWS |
CREATE_NEW_PLOT |
SET_PLOT_OPTION |
LIST_PLOT_OPTIONS |
REMOVE_PLOT |
LIST_ALL_PLOTS |
LIST_CURRENT_DIRECTORIES |
SET_APPLICATION_DIRECTORY |
SET_WORKING_DIRECTORY |
SHOW_EXPRESSION |
SET_VARIABLE_VALUE |
REMOVE_VARIABLE |
LIST_ALL_VARIABLES |
SET_FUNCTION_EXPRESSION |
LIST_ALL_FUNCTIONS |
REMOVE_FUNCTION |
EDIT_SYMBOL |
EDIT_PARAMETER |
LIST_SYMBOLS |
LIST_PARAMETERS |
|
CREATE_NODE_GROUP |
|
|
LIST_NODE_GROUPS |
REMOVE_NODE_GROUP |
LIST_CORE_NODES |
CREATE_CORE_NODE |
REMOVE_CORE_NODE |
SELECT_CORE_NODE |
-------------------------------------------------------------------------------
use HELP_CORE for thermodynamic and kinetics-specific commands
use HELP_SIMULATION for CA-FE simulation-specific commands
use HELP_MONTECARLO for monte-carlo-specific commands
-------------------------------------------------------------------------------
The commands listed above are part of the 'workspace' module of
MatCalc and relate to creating and modifying workspaces and windows
within workspaces. As can be seen from the last line of the above
transcript, 'HELP_CORE' gives access to another series of commands
relating to the 'core' of the program, i.e. the calculations themselves:
_mcore: help_core
-------------------------------------------------------------------------------
available commands in mc_core module:
-------------------------------------------------------------------------------
RESTART |
LICENSE_INFO |
GIBBS_CALC_STATUS |
TEST_COMMAND |
STOP_CURRENT_ACTION |
LIST_DATABASE_CONTENTS |
SELECT_ELEMENTS |
SELECT_PHASES |
SET_REFERENCE_ELEMENT |
ENTER_COMPOSITION |
SET_TEMPERATURE_CELSIUS |
SET_TEMPERATURE_KELVIN |
SET_PRESSURE |
SET_AUTOMATIC_STARTVALUES |
APPLY_TANGENT_CONSTRUCTION |
CALCULATE_EQUILIBRIUM |
SEARCH_PHASE_BOUNDARY |
STEP_EQUILIBRIUM |
LIST_EQUILIBRIUM |
LIST_CORE_STATUS |
SET_STEP_OPTION |
LIST_STEP_OPTIONS |
CHANGE_PHASE_STATUS |
LIST_PHASE_STATUS |
CREATE_NEW_PHASE |
REMOVE_PHASE |
<<CORE>> |
<<NODES>> |
<<SYMBOLIC>> |
<<IO>> |
<<PRECIPITATION>> |
<<STATE>> |
<<BUFFER>> |
<<TABLES>> |
<<TRANSFORMATIONS>> |
<<HEAT_TREATMENTS>> |
<<EXPORT>> |
|
|
_mcore:
The 'core' contains several subsections, given in triangular brackets
below the list of commands. These can be opened by typing in 'HELP_CORE' again with the name of the subsection. For example 'HELP_CORE
IO' lists the input/output commands.
_mcore: help_core io
-------------------------------------------------------------------------------
available commands in mc_core module: IO
-------------------------------------------------------------------------------
OPEN_THERMODYN_DATABASE |
READ_THERMODYN_DATABASE |
READ_MOBILITY_DATABASE |
READ_PHYSICAL_DATABASE |
|
|
_mcore:
Notes on syntax
1. Although the commands listed above contain underscores '_',
the hyphen '-' can be used interchangeably with the underscore
when typing commands. Note, however, that this is not the case
in names of phases such as 'BCC_A2', which require the underscore.
2. Commands are case-insensitive.
3. Any unambiguous abbreviations of the commands are allowed.
For example, 'open_th' or even 'o_t' are acceptable abbreviations
of 'open_thermodyn_database'. Using an ambiguous abbreviation,
such as 'read', gives a list of all possible commands with that
abbreviation, together with a message indicating that the command
was ambiguous:
_mcore: read
READ_WORKSPACE
READ_THERMODYN_DATABASE
READ_MOBILITY_DATABASE
READ_PHYSICAL_DATABASE
*** error *** ambiguous command
_mcore:
2. Example: calculating an equilibrium using the command-line
The use of command-lines will be illustrated with a simple example:
setting up a workspace and calculating an equilibrium at a single
temperature. This is the same calculation as in Tutorial
2: an
equilibrium at 700°C in a Fe-0.4 wt.% C system containing the
phases LIQUID, FCC_A1, BCC_A2 and CEMENTITE.
Start with a new workspace. (Warning! Using the 'new_workspace' command
does not prompt the user to save any previously open workspace
files, so make sure any necessary changes are saved first.)
_mcore: new_workspace
<script(0)>
<script(0)> $ running autonew.mcs script ...
<script(0)> m-gui-w 0 0 500 900 450
<script(0)> n-gui-w a6
<script(0)> m-gui-w . 500 0 500 450
<script(0)> n-gui-w a5
<script(0)> m-gui-w . 0 0 450 300
<script(0)> set-workspace-prop m n
<script(0)>
<script(0)> $ ready ...
<script(0)>
_mcore:
Open the thermodynamic database. This is equivalent to clicking
'Open' in the 'Global > Databases' dialogue box.
_mcore: open_thermodyn_database
name for thermodynamic database ('*' for list) /mc_sample_fe.tdb/:
The console prompts the user for the name of a database. The default
option is given between slashes '/../' (By typing '*' and pressing 'enter', the content of the ...\MatCalc\database directory is shown). Press 'enter' to accept
the default 'mc_sample_fe.tdb' database. Find out which elements and phases are in the database using
'list_database_contents':
_mcore: list_database_contents
(e)quilib/(d)iffusion/(p)hysical /e/: e
equilibrium database file: C:/Programme/MatCalc/database/mc_sample_fe.tdb
# of elements in database: 15
VA, AL, C, CR, CU, FE, MN, MO, N, NB, NI, SI, TI, V, W
# of phases in database: 15
LIQUID |
FCC_A1 |
BCC_A2 |
HCP_A3 |
ALN |
CEMENTITE |
CU_S |
GRAPHITE |
M23C6 |
M6C |
M7C3 |
LAVES_PHASE |
KSI_CARBIDE |
M3C2 |
SIGMA |
V3C2 |
CR2VC2 |
FE4N |
MN6N4 |
MN6N5 |
ZET |
Select the required elements using 'select_elements
c fe'. A message
appears to indicate that C has been selected, and Fe has been ignored
because it was already selected by default.
_mcore: select_elements c fe
element 'C' selected
element 'FE' ignored
Next select the phases. Any unambiguous abbreviation is acceptable
for the phase names. Messages appear to confirm that these phases
have been selected.
_mcore: select_phases liq bcc fcc cem
phase 'LIQUID' selected
phase 'BCC_A2' selected
phase 'FCC_A1' selected
phase 'CEMENTITE' selected
Read in the thermodynamic data. This is equivalent to clicking
'read' in the 'Databases' dialogue box.
_mcore: read_thermodyn_database
Enter the composition. There are three available unit qualifiers:
x (mole fraction), u (u-fraction) and w (weight fraction). In addition,
appending 'p' to any of these gives the unit in percent. See the
example below, in which the composition is specified in weight
percent.
_mcore: enter_composition
unit qualifier (X/U/W + P) /x/: wp
enter amount (e.g. Mn=0.32 C=0.01): c=0.4
Open 'Databases', 'Composition' and 'Phase
Status' from the 'Global' menu and note that the system setup entered using the command-line
is shown in the GUI windows. Console and GUI versions of commands
can be used completely interchangeably.
Set the temperature to 700°C. Note that there are two commands
for temperature, 'set_temperature_celsius' and 'set_temperature_kelvin',
depending on the units of interest.
_mcore: set_temperature_celsius 700
Impose automatic start-values and calculate an equilibrium.
_mcore: set_automatic_startvalues
_mcore: calculate_equilibrium
Note the results in 'phase summary' window: the stable phases
are BCC_A2 and CEMENTITE as expected.
3. Evaluating expressions
As well as entering commands, the console can be used to evaluate
numerical expressions, MatCalc variables and user-defined expressions
and functions.
Numerical expressions
Any numerical expression can be evaluated using the command 'SHOW_EXPRESSION' ('show' or 'sh' are acceptable abbreviations):
_mcore: show 4/5
4/5 =
0.8
_mcore: show pi
pi =
3.14159265359
Note the priority rules and the use of parentheses to override
these, e.g.:
_mcore: show 4/5*3
4/5*3 =
2.4
_mcore: show 4/(5*3)
4/(5*3) =
0.266666666667
_mcore: show 4+4*2
4+4*2 =
12
_mcore: show (4+4)*2
(4+4)*2 =
16
Expressions in x
Expressions in terms of the current value of the stepped variable,
x, can be evaluated using 'show_expression', as shown below. (The
value of x is currently zero because no stepped calculation has
so far been performed in this workspace.)
_mcore: show 3*x
3*x =
0
Functions in x can be defined and then evaluated.
_mcore: set-function-expression
which function: function1
enter expression: 3*x
_mcore: show function1
function1 =
0
Pressing the up-arrow recalls the latest command to be entered.
Further use of this up-arrow scrolls through the command history
in reverse chronological order. Commands are given with the full names and chosen options, e.g.:
_mcore: SET_FUNCTION_EXPRESSION function1 3*x
The command-line can then be edited:
_mcore: SET_FUNCTION_EXPRESSION function2
enter expression: x**2
This is the expression for x2. The syntax 'x^2' can
also be used for the same purpose:
_mcore: SET_FUNCTION_EXPRESSION
which function
/function2/: function3 enter expression: x^2
The functions just defined can now be found by opening the 'Functions' tab in 'Global > Variables & functions', and in the 'variables' window under 'functions'. They can be plotted in a new window as
follows:
Firstly, create a new window and enter the window-type code. These
codes can be found under 'View > Create new window'. The standard
x-y plot is 'p1'.
_mcore: new_gui_window
enter window-type code: p1
Next, add a new series using set-plot-option and choosing the
following options:
_mcore: set-plot-option
enter plot ID /1/:
(t)itle/(a)xis/(l)egend/(h)istogram/(s)eries: s
(n)ew/(e)dit/(r)emove/rena(m)e/(l)ock/(d)erive/(c)onvert to table:
n
(b)uffer results/(t)able/experimental data/(f)unction/expression:
f
expression in variable 'x': function1
definition range /auto/: -10..10
Finally, add the other two series by recalling and editing the
previously used command.
_mcore: SET_PLOT_OPTION 1 S N F function2 -10..10
_mcore: SET_PLOT_OPTION 1 S N F function3 -10..10
The resulting plot should look like this:

Expressions using MatCalc variables
It is also possible to define functions made up of MatCalc variables.
Here, two functions similar to those discussed in Tutorial 6 are
defined. The built-in variables can be copied and pasted from the
'variables' window to the console using the right-click menus or
Ctrl+C and Ctrl+V.
_mcore: SET_FUNCTION_EXPRESSION function4 F$BCC_A2*X$BCC_A2$C
_mcore: SET_FUNCTION_EXPRESSION function5 F$CEMENTITE*X$CEMENTITE$C
These new functions can then be evaluated using 'show':
_mcore: show function4
function4 =
0.000627105512124
_mcore: sh function5
function5 =
0.01770390510026
Expressions can be built up from existing functions and variables:
_mcore: show function4+function5
function4+function5 =
0.0183310105147
Below, it is confirmed that, at 700°C, function4 + function5
= XS$C i.e. all the carbon in the system is in the form of either
BCC_A2 or cementite, since these are the only two phases to be
stable at this temperature.
_mcore: show XS$C-(function4+function5)
xs$C-(function4+function5) =
0
The next tutorial discusses the use of command-lines in scripts
to facilitate repetitive or complex tasks.
‹‹ to the Top ›› ‹‹ to
the Tutorial files ›› |