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

  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
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:

 MatCalc plot

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

tutorials/t12.txt · Last modified: 2016/07/29 09:26 by pwarczok