no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+===== 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 {{:tutorials:t12:script:t12_6021003.mcs|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.
+<code>
+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
+-------------------------------------------------------------------------
+</code>
+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:
+<code>
+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>>
+</code>
+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.
+<code>
+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
+</code>
+==== 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:
+<code>
+MCORE: read
+READ_WORKSPACE
+READ_THERMODYN_DATABASE
+READ_MOBILITY_DATABASE
+READ_PHYSICAL_DATABASE
+READ_BINARY_FILE
+*** error *** ambiguous command
+_mcore:
+</code>
+===== 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 [[tutorials:T2 | 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.)
+<code>
+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 ...
+</code>
+Open the thermodynamic database. This is equivalent to clicking **'Open'** in the **'Global > Databases'** dialogue box.
+<code>
+MCORE: open_thermodyn_database
+name for thermodynamic database ('*' for list) /mc_sample_fe.tdb/:
+</code>
+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.
+<code>
+MCORE: open_thermodyn_database
+name for thermodynamic database ('*' for list) /mc_sample_fe.tdb/:
+opening database 'mc_fe.tdb' ...
+</code>
+Find out which elements and phases are in the database using **'list_database_contents'**:
+<code>
+MCORE: list_database_contents
+(e)quilib/(d)iffusion/(p)hysical /e/:
+</code>
+Type in **'e'**, to show the content of the opened equilibrium database
+<code>
+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
+</code>
+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.
+<code>
+MCORE: select_elements c fe
+element 'C' selected
+element 'FE' ignored
+</code>
+Next select the phases. Any unambiguous abbreviation is acceptable for the phase names. Messages appear to confirm that these phases have been selected.
+<code>
+MCORE: select_phases liq bcc_a2 fcc cem
+phase 'LIQUID' selected
+phase 'BCC_A2' selected
+phase 'FCC_A1' selected
+phase 'CEMENTITE' selected
+</code>
+Read in the thermodynamic data. This is equivalent to clicking **'read'** in the 'Databases' dialogue box.
+<code>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
+</code>
+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.
+<code>
+MCORE: enter_composition
+unit qualifier (X/U/W + P) /x/: wp
+enter amount (e.g. Mn=0.32 C=0.01): c=0.4
+</code>
+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.
+<code>MCORE: set_temperature_celsius 700</code>
+Impose automatic start-values and calculate an equilibrium.
+<code>
+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 -
+</code>
+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):
+<code>
+MCORE: show 4/5
+/5 =
+.8
+MCORE: show pi
+pi =
+.14159265359
+</code>
+Note the priority rules and the use of parentheses to override these, e.g.:
+<code>
+MCORE: show 4/5*3
+/5*3 =
+.4
+MCORE: show 4/(5*3)
+/(5*3) =
+.266666666667
+MCORE: show 4+4*2
++4*2 =
+MCORE: show (4+4)*2
+(4+4)*2 =
+</code>
+==== 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.)
+<code>
+MCORE: show 3*x
+*x =
+</code>
+Functions in x can be defined and then evaluated.
+<code>
+MCORE: set-function-expression
+which function: function1
+enter expression: 3*x
+MCORE: show function1
+function1 =
+</code>
+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.:
+<code>_mcore: SET_FUNCTION_EXPRESSION function1 3*x</code>
+The command-line can then be edited, e.g. replace **'function1'** by **'function2'**:
+<code>
+MCORE: SET_FUNCTION_EXPRESSION function2
+enter expression: x**2
+</code>
+This is the expression for **x<sup>2</sup>**. The syntax **'x^2'** can also be used for the same purpose:
+<code>
+MCORE: SET_FUNCTION_EXPRESSION
+which function /function2/: function3
+enter expression: x^2
+</code>
+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'**.
+<code>
+MCORE: new_gui_window
+enter window-type code: p1
+</code>
+Next, add a new series using set-plot-option and choosing the following options (press Enter, if there is no sign behind the colon):
+<code>
+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
+</code>
+Finally, add the other two series by recalling and editing the previously used command.
+<code>
+MCORE: SET_PLOT_OPTION 1 S N F function2 -10..10
+MCORE: SET_PLOT_OPTION 1 S N F function3 -10..10
+</code>
+The resulting plot should look like this:\\
+{{:tutorials:t12:img:t12_plot1_functions_plotted_2016.png?650| 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 [[tutorials:T6 | 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.
+<code>
+MCORE: SET_FUNCTION_EXPRESSION function4 F$BCC_A2*X$BCC_A2$C
+MCORE: SET_FUNCTION_EXPRESSION function5 F$CEMENTITE*X$CEMENTITE$C
+</code>
+These new functions can then be evaluated using **'show'**:
+<code>
+MCORE: show function4
+function4 =
+,000628639871334
+MCORE: sh function5
+function5 =
+,0177023706434
+</code>
+Expressions can be built up from existing functions and variables:
+<code>
+MCORE: show function4+function5
+function4+function5 =
+.0183310105147
+</code>
+Below, it is confirmed that, at 700°C, function4 + function5 = <nowiki>XS$C</nowiki> 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.
+<code>
+MCORE: show XS$C-(function4+function5)
+xs$C-(function4+function5) =
+</code>
+The next tutorial discusses the use of command-lines in scripts to facilitate repetitive or complex tasks.
+==== Command history ====
+The command history window can be made to appear by selecting the console window and either clicking on the up-arrow icon or  pressing **Ctrl + up-arrow**. This window gives a chronological list of all the commands entered in the Console.
+{{:tutorials:t1:img:t1_command_history_window_2016.png| MatCalc command history window}}
+A command can be selected using the mouse pointer or arrow keys. Right-clicking on the command displays the following menu. On the right-hand side of the menus in MatCalc are keyboard shortcuts for the more commonly used commands. It can be seen from the image below that it is sufficient to press the **Enter** key to execute the selected command.
+{{:tutorials:t1:img:t1_command_history_menu_2013.png| MatCalc command history menu}}
+Previously used commands can also be accessed in the Console window itself; pressing the up-arrow key displays the most recently entered command, and pressing it repeatedly scrolls through recent commands in reverse chronological order. The command displayed can be edited then executed by pressing the **Enter** key.
+===== Consecutive articles =====
+The tutorial is continued in article [[tutorials:T13 | T13 - Introduction to scripting (1: Equilibrium calculations)]]
+Go to [[:tutorials|MatCalc tutorial index]].