This is an old revision of the document!
Table of Contents
T12: Using the MatCalc console
This tutorial was tested on
MatCalc version 6.00 rel 0.100
license: free
database: mc_fe.tdb
Complimentary files
Click here to view the script for this tutorial
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
General remark to 6.00.0100 version
Due to some development activities, the commands are to be typed into the 'MatCalc 5 console' window - this are the lines begining here with 'MCORE:'. The output messages are displayed in the 'console' window, as always.
Basics
Getting help and listing available commands
Typing '?' or 'HELP_WORKSPACE' in the 'MatCalc 5 console' window shows a list of available commands.
MCORE: ? ------------------------------------------------------------------------- available commands in workspace module: ------------------------------------------------------------------------- ? HELP_WORKSPACE HELP_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 TEST_COMMAND STOP_CURRENT_ACTION STOP_RUN_SCRIPT NEW_GUI_WINDOW REMOVE_GUI_WINDOW MOVE_GUI_WINDOW SET_GUI_WINDOW_PROPERTY UPDATE_GUI_WINDOWS LIST_GUI_WINDOW_PROPS LIST_ALL_GUI_WINDOWS ALLOW_WINDOW_UPDATE SET_PROGRESS_INDICATOR CREATE_NEW_PLOT SET_PLOT_OPTION LIST_PLOT_OPTIONS REMOVE_PLOT LIST_ALL_PLOTS COPY_PLOT_TO_CLIPBOARD COPY_FRAME_TO_CLIPBOARD EXPORT_PLOT_TO_FILE EXPORT_FRAME_TO_FILE LIST_CURRENT_DIRECTORIES SET_APPLICATION_DIRECTORY SET_WORKING_DIRECTORY SET_LICENSE_FILEPATH SHOW_EXPRESSION SET_VARIABLE_VALUE INPUT_VARIABLE_VALUE REMOVE_VARIABLE LIST_ALL_VARIABLES LIST_INTERNAL_VARIABLES SET_VARIABLE_STRING INPUT_VARIABLE_STRING FORMAT_VARIABLE_STRING REMOVE_STRING_VARIABLE LIST_ALL_STRING_VARIABLES SEND_OUTPUT_STRING SEND_CONSOLE_STRING SEND_DIALOG_STRING SET_FUNCTION_EXPRESSION LIST_ALL_FUNCTIONS REMOVE_FUNCTION EDIT_SYMBOL EDIT_PARAMETER LIST_SYMBOLS LIST_PARAMETERS ------------------------------------------------------------------------- use HELP_MODULE for module 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_MODULE' gives access to another series of commands relating to the current module of the program ('core'), i.e. the calculations themselves:
MCORE: help_module ------------------------------------------------------------------------- available commands in mc_core module: ------------------------------------------------------------------------- RESTART LICENSE_INFO GIBBS_CALC_STATUS 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 CALC_PARTITION_RATIO <<CORE>> <<NODES>> <<SYMBOLIC>> <<IO>> <<PRECIPITATION>> <<STATE>> <<BUFFER>> <<TABLES/ARRAYS>> <<TRANSFORMATIONS>> <<HEAT_TREATMENTS>> <<EXPORT>>
The 'mcore' module contains several subsections, given in triangular brackets below the list of commands. These can be opened by typing in 'HELP_MODULE' again with the name of the subsection. For example 'HELP_MODULE IO' lists the input/output commands.
MCORE: help-module io ------------------------------------------------------------------------- available commands in mc_core module: IO ------------------------------------------------------------------------- OPEN_THERMODYN_DATABASE TEST_EXIST_TD_DATABASE READ_THERMODYN_DATABASE READ_MOBILITY_DATABASE TEST_EXIST_MOB_DATABASE READ_PHYSICAL_DATABASE TEST_EXIST_PH_DATABASE SET_LOG_FILE WRITE_BINARY_FILE READ_BINARY_FILE SET_AUTOSAVE_FILENAME TEST_EXIST_FILE
Notes on syntax
- 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.
- Commands are case-insensitive.
- 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 READ_BINARY_FILE *** error *** ambiguous command _mcore:
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/core)> $ phase details: create and move <script(0/core)> new-gui-window a6 <script(0/core)> move-gui-window . 500 0 500 450move-gui-window window-id=. x-axis=500 y-axis=0 width=500 height=450 <script(0/core)> $ phase summary: create and move <script(0/core)> new-gui-window a5 <script(0/core)> move-gui-window . 0 0 450 300move-gui-window window-id=. x-axis=0 y-axis=0 width=450 height=300 <script(0/core)> $ clear modified-flag <script(0/core)> set-workspace-property m n <script(0/core)> $ ready ...
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). Type 'mc_fe.tdb' to select the improved database.
MCORE: open_thermodyn_database
name for thermodynamic database ('*' for list) /mc_sample_fe.tdb/:
opening database 'mc_fe.tdb' ...
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/:
Type in 'e', to show the content of the opened equilibrium database
MCORE: list_database_contents
(e)quilib/(d)iffusion/(p)hysical /e/:
equilibrium database file: mc_fe.tdb
# of elements in database: 25
VA, AL, B, C, CO, CR, CU, FE, H, HF, LA, MN, MO, N, NB, NI, O, P, PD, S, SI, TI, V, W, Y
# of phases in database: 122
LIQUID FCC_A1 BCC_A2
H_BCC BCC_DISL HCP_A3
ALPHA_MN BETA_MN BETA_RHOMBO_B
DIAMOND_A4 GRAPHITE BCC_B2
CHI_A12 CO3MO CO3V
COV3 CR3MN5 G_PHASE
LAVES_PHASE MNNI MNNI2
MNNI_T3 MU_PHASE MU_PHASE_I
ETA NITI2 PI_PHASE
R_PHASE SIGMA FE17Y2
NI5Y PDFE_L12 PDMN_AF
PDMN_P PDMN_B2 PD2MN
PD3MN PD5MN3 PD6FE5MN2
CEMENTITE CR2VC2 K_CARB
KSI_CARBIDE M3C2 M6C
M7C3 M12C M23C6
MOC_ETA V3C2 WC
EPS_CARB ETA_CARB FE24C10
KSI_FE5C2 ALN ALN_EQU
BN_HP4 CR3NI2SIN FE4N
MN6N4 MN6N5 MNSIN2
SI3N4 ZET CRB
CR2B CR5B3 FEB
FENBB FE3NB3B4 M2B
MNB2 MNB4 O_MN2B
MN3B4 MOB MOB2
MO2M1B2 NBB NB3B2
M5B6 TIB TIB2
TI3B4 A_CHALC ANILITE
B_CHALC COVELLITE CU2S
DIGENITE DISULF DJURLEITE
FC_MONO FC_ORTHO FES_P
MNS_Q PYRR TIS
TI4C2S2 CORUND HALITE
HF1O2_M HF1O2_T HF1O2_C
LA2O3_A LA2O3_H LA2O3_C
SIO2 SPINEL TIO2
TI2O3 TRID Y2O3_C
Y2O3_H YALO3 Y4AL2O9
Y2TIO5 Y2TI2O7 O1_GAS
M2P M3P
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_a2 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 reading thermodynamic data 'mc_fe.tdb' ... collecting symbols 'mc_fe.tdb' ... elements: VA C FEhases: LIQUID FCC_A1 BCC_A2 CEMENTITE Gibbs: 4 Phases / 0 Composition-Set(s) created Gibbs: 30 functions linked ... Gibbs: T = 1273.160000 K, P = 101325.000000 Pa, moles = 1
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 iter: 13, time used: 0,02 s T: 700 C (973,16 K), GibbsEnergy: -39934,665 J - OK -
Note the results in 'phase summary' window: the stable phases are BCC_A2 and CEMENTITE as expected.
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, e.g. replace 'function1' by 'function2':
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 (press Enter, if there is no sign behind the colon):
MCORE: set-plot-option enter plot ID /1/: (t)itle/(a)xis/(l)egend/(g)rid/(h)istogram/tt(p)/(s)eries: s (n)ew/(e)dit/(r)emove/rena(m)e/(l)ock/(d)uplicate and lock deri(v)e/(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,000628639871334 MCORE: sh function5 function5 = 0,0177023706434
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.
Consecutive articles
The tutorial is continued in article T13 - Introduction to scripting (1: Equilibrium calculations)
Go to MatCalc tutorial index.
