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_2017.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.
+===== Consecutive articles =====
+The tutorial is continued in article [[tutorials:T13 | T13 - Introduction to scripting (1: Equilibrium calculations)]]
+Go to [[:tutorials|MatCalc tutorial index]].