forked from sundmanbo/opencalphad
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathochelp.hlp
3882 lines (3073 loc) · 154 KB
/
ochelp.hlp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[12pt]{article}
\usepackage[latin1]{inputenc}
\topmargin -5mm
\oddsidemargin -1mm
\evensidemargin -1mm
\textwidth 170mm
\textheight 225mm
\parskip 2mm
\parindent 3mm
\usepackage[firstpage]{draftwatermark}
\SetWatermarkScale{4}
% this should allow \subsubsubsection ...
\newcommand{\subsubsubsection}[1]{\paragraph{#1}\mbox{}\\}
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{4}
%\pagestyle{empty}
%
% LOOK for ALERT: for checks of source code!!
%
% look for this to continue update
%%%%%%%%%%%%%%% >>> end of current editing for version 5 2018.01.08
%
% This is a file for a printable PDF and HTML versions of the user guide
% AND as on-line help, either directly or processed to remove LaTeX specials
% >>>>>>>>>>> Convert to HTML for online help: htlatex ochelp5
%
%---------------------------------------------------
%
% The current version of this is generated manually but eventually a
% software program should be developed to update this automatically whenever
% the software is changed
%
%---------------------------------------------------
%
% SOME IMPORTANT ADVICE:
%
% The commands and subcommands are arranged alphabetically
%
% It will be difficult to update the help text for the
% questions after the commands and subcommands as they are normally
% not part of the command monitor.
%
% The _ used in many commands must be replaced by \_ or just -
%
%---------------------------------------------------
%
% The on-line help software saves the line of commands starting
% from the prompt. If the user types ``?'' as answer to a question it will
% search the help file for the appropriate help text starting from the
% the command given at the prompt, then subcommand in two levels
% and finally for the question texts.
%
% In the file it will search lines starting with %\section or %\sub...section
% and save the line numbers when it finds a match. The text between the
% last matching line found and the following %\section or %\sub...section
% will be printed as help text.
% Then the question will be asked again.
%
% The question text may be difficult to update as already mentioned.
% ADDING ONLINE HELP INFORMATION IN THIS FILE:
% A command must always have a %\subsub...section{command} line
% FOR QUESTIONS after a command
% you must provide a comment line as %\subsubsection{question}
% or %\subsubsubsection{question}
% depending on the number of subsub... the previous command has
% AT LEAST 12 CHARACTER OF THE QUESTION SHOULD BE IN THE COMMENT LINE !!
% The help software saves the hirearchy of the command down to the question
% The help software searches top down for matching commands/questions.
% when it finds a matching command/question in this file it searched
% one level further down until is has match with the last level. It saves
% that line number as the first line of help text
% and then searches for the next %\subsub... and when it finds one
% with same, less or more number of subsub...
% it takes that as the last line of help text.
%
%
%---------------------------------------------------
%
\begin{document}
\begin{center}
{\Huge \bf User Guide to the
OpenCalphad software package
version 5.0
}
\bigskip
DRAFT
Bo Sundman, \today
\end{center}
\newpage
This page intentionally blank
\newpage
\tableofcontents
\newpage
\section{Introduction}
The development of the OpenCalphad (OC) sofware was started by a small
group of dedicated scientists who wanted to provide an open source
multicomponent thermodynamic software. It aims to provide a free high
quality software for thermodynamic calculations, including property
and phase diagrams, assessment of databases and a thermodynamic
library for simulations for inorganic systems i.e. gases. liquids,
alloys and other materials using many different kinds of models for
the phases. There are three basic papers published about
OC~\cite{15Sun1,15Sun2,16Sun}. General information about
thermodynamic models, calculations and assessments based on the
Calphad technique can be found in the book by Lukas et
al~\cite{07Luk}. The software is provided free with a GNU GPL
license.
In OC there is also a framework to store different kinds of materials
properties that depend on temperature, pressure and composition when
such properties are related to the phases of the system. The OC
software can also be used to assess model parameters for such
properties from experimental and theoretical values.
Complimentary (and maybe sometimes contradictory, I am not perfect)
information about the OC software can be found in getting-started.pdf,
news-oc5.pdf and the other parts of the OC documentation.
\section{Some general features}
The different parts of the OC software are documented separately for
each module: thermodynamic models (GTP), equilibrium calculations
(HMS), step/map/plot routines (SMP) and the application software
interface (OCASI/TQ). OC uses the free numerics packages LAPACK and
BLAS and a free least square routine, LMDIF~\cite{lmdif}, developed at
Argonne 1980, for assessments. For graphics OC generates a command
file which can be plotted with the free GNUPLOT~\cite{gnuplot}
software. If GNUPLOT is properly installed this is done automatically
by OC.
\subsection{Command line user interface}
OC is operated by commands typed by the user or read from a macro
file. The command monitor has a menu of command and each of these
usually has sub-menus and finally some questions may be asked like
phase names, a value or an expression. In most cases a default answer
is provided which can be selected by just pressing the RETURN key or
by typing a comma, ``,'', on the same line as the command. At all
levels the user should be able to type a ? and get some help, usually
an extract from this manual, sometimes just a menu or examples of
answers.
If you prefer a graphical user interface (GUI) you are welcome to add
this to the OC software.
\subsubsection{Popup window for read/save}\label{sc:popup}
There is a problem using a command line interface when you want to
open a file for reading or saving unless this file is on the same
directory as where you started the program. Thus from version 5.018
there is a popup window to open a file (for a macro, a database or to
save a calculation). In this window you can browse your directories
to find the file.
This has some consequencies for editing your macro files which you
should be aware of and which are explained below. The code for the
popup window, tinyfiledialogs, is written in C by Guillaume Vareille.
You can turn off the open file popup window feature with the command
{\em set advanced popup Y}. You can turn it on again with the same
command finishing with anything but Y.
\begin{itemize}
\item The directory where you start the session with OC is called the
``working directory''. On a linux system you can find this
directory by typing ``pwd'' before starting OC (or if you type {\em
@pwd} inside OC). On a Windows system you can see the working
directory and its files if you type {\em @dir} inside OC.
\item When the popup window is opened the directories and files
matching the ``filter'' in the working directory should be listed.
If not you can select a directory inside the popup window. The
filter when open a macro file is ``OCM'' and when opening a database
file it is ``TDB'' which means only files with these extensions are
listed. You can change the directory in the popup window to select
the file you want and you can read a file with another extension.
OC will save internally the directory where you start the macro.
\item Inside a macro file you normally read a TDB file and if you do
not specify the name of the database on the same line as the command
{\em read tdb} the popup window will open so you can specify the
file in this window.
\item But normally you know which database you want to use inside the
macro and if you give the file name on the same line as the commad:
{\em read tdb filename} the popup window will not open and OC will
search for the specified database file starting from the ``working
directory''. But if the database file is in the same directory as
the macro file you MUST prefix ``filename'' with ``./'', i.e. {\em
read tdb ./filename}. You may include directories in
``filename'', (including ``../'' to go to the directory above). OC
will replace the ``./'' by the directory where you started the macro
or prefix ``../'' by this directory.
\item In the macro file you can give the full path to the file to be
opened but that is rather clumsy.
\item When you open a file for write inside a macro, like output from
a plot, you can also specify the file name in the command prefixed
by ``./'' if you want to save the file on the same directory as the
macro file. Otherwise it will be saved at the working directory.
\item If you use the switch ``/output='' or ``/append='' after a
command to redirect output from the command you can also use the
popup window to specify the file name or use a filename with or
without the prefix ``./''. The filter in this case is ``DAT''.
\end{itemize}
Opening files on different directories can be complicated inside OC.
For example during assessments you may use many different files for
generating graphics and unformatted save files. Preferably you keep
all of these on the same directory.
You are welcome to provide feedback on this popup feature and other
parts of the user interface.
\subsection{Names and symbols}
There are many symbols and names used in this package. A symbol or
name MUST start with a letter A-Z. It usually can contain digits and
the underscore character after the initial letter. All names are CASE
INSENSITIVE, i.e. fe, FE, fE and Fe is the same. Some special symbols
are used:
\begin{itemize}
\item /- is used to denote the electron. /+ or /- -1 can be used for a
positive charge.
\item \# are used to identify composition sets after a phase name or
sublattice after a constituent name.
\item \& are used in some parameter identifiers to specify the
constituent for the parameter, like for mobilities, the mobility of
Fe in the BCC phase is denoted MQ\&FE(BCC).
\end{itemize}
A name of an element is one or two characters, a species maximum 24
characters (note that a species name does not have to be its
stoichiometric formula). A phase name is 24 characters but can also
have a pre- and suffix 4 characters long and possibly a composition
set number after a hash symbol, \#.
State variable symbols and TP-fun symbols can be 16 characters long.
TP-funs are expressions used to describe the $T$ and $P$ dependence of
model parameters.
For user input it is possible to use abbreviations of names but you
must be careful with names that have the same abbreviation and avoid
phase names that are abbreviations of another phase!
\subsection{Phases, composition sets and phase tuples}
Each phase in a system has a name and a thermodynamic model. The
models are explained in a separate documentation. The phases can be
entered interactivly or read from a database or a saved file together
with the last calculation.
In some cases a phase can be stable with two ore more different
compositions for example inside miscibility gaps or when the phase has
order/disorder transitions. In such a case you use a composition set
index to separate these. The composition set index is appended to the
phase name preceeded by a hash ``\#'' character, like liquid\#2.
Composition sets can be created manually, see the command {\bf AMEND
PHASE} in section~\ref{sc:amend_phase_cs} or automatically by the
grid minimizer or application software.
The phase tuple has been introduced to have a single index for both
phases and composition sets in application software. The tuple index
thus contain both the phase number and the composition set index. The
array of tuple indices is updated internally whenever a new
composition set is created or deleted.
\subsection{The use of wildcards for names}
In many cases you can use an asterix ``*'' as a name and this normally
means ``all''. For setting status of phases you can use the special
``*S'' for all suspended phase, ``*D'' for all dormant phases.
\subsection{State variables}
\begin{table}[!ht]
\caption{A preliminary table with the state variables and their
internal representation. Some model parameter properties are also
included. The "z" used in some symbols like Sz means the optional
normalizing symbol M, W, V or F.}\label{tab:statev}
{\small
\begin{tabular}{|llccll|}\hline
Symbol & Id & \multicolumn{2}{c}{Index} & Normalizing & Meaning\\
& & 1 & 2 & suffix & \\\hline
\multicolumn{6}{|c|}{Intensive properties}\\\hline
T & 1 & - & - & - & Temperature\\
P & 2 & - & - & - & Pressure\\
MU & 3 & component & -/phase & - & Chemical potential\\
AC & 4 & component & -/phase & - & Activity\\
LNAC & 5 & component & -/phase & - & LN(activity)\\\hline
\multicolumn{6}{|c|}{Extensive and normallized properties}\\\hline
U & 10 & -/phase\#set & - & - & Internal energy for system\\
UM & 11 & -/phase\#set & - & M & Internal energy per mole\\
UW & 12 & -/phase\#set & - & W & Internal energy per mass\\
UV & 13 & -/phase\#set & - & V & Internal energy per m$^3$\\
UF & 14 & phase\#set & - & F & Internal energy per formula unit\\
Sz & 2z & -/phase\#set & - & - & entropy\\
Vz & 3z & -/phase\#set & - & - & volume\\
Hz & 4z & -/phase\#set & - & - & enthalpy\\
Az & 5z & -/phase\#set & - & - & Helmholtz energy\\
Gz & 6z & -/phase\#set & - & - & Gibbs energy\\
NPz & 7z & phase\#set & - & - & Moles of phase\\
BPz & 8z & phase\#set & - & - & Mass of phase\\
Qz & 9z & phase\#set & - & - & Stability of phase\\
DGz & 10z & phase\#set & - & - & Driving force of phase\\
Nz & 11z & -/phase\#set/comp & -/comp & - & Moles of component\\
X & 111 & phase\#set/comp & -/comp & 0 & Mole fraction\\
X\% & 111 & phase\#set/comp & -/comp & 100 & Mole per cent\\
Bz & 12z & -/phase\#set/comp & -/comp & - & Mass of component\\
W & 122 & phase\#set/comp & -/comp & 0 & Mass fraction\\
W\% & 122 & phase\#set/comp & -/comp & 100 & Mass per cent\\
Y & 130 & phase\#set & const\#subl & -& Constituent fraction\\\hline
\multicolumn{6}{|c|}{Some model parameter identifiers}\\\hline
TC & - & phase\#set & - & - & Curie temperature\\
BMAG & - & phase\#set & - & - & Aver. Bohr magneton number\\
MQ\&X & - & phase\#set & constituent & - & Mobility of X\\
THET & - & phase\#set & - & - & Debye temperature\\\hline
\end{tabular}}
\end{table}
A state variable in a thermodynamic system has a value which at
equilibrium is independent of the way the system has reach its current
state. All state variables available in OC are listed in
Table~\ref{tab:statev}. They are used to set conditions and to obtain
results from an equilibrium calculation. It is possible to use state
variables also when close to the equilibrium state for example when
simulating a phase transformation.
\subsection{Model parameters}
All data is organized relative to a phase and the phase is identified
by a name. Each phase can have a different model for the composition
dependence but the way to enter model parameters is the same for all
models. However, the meaning of a model parameter will depend on the
model of the phase.
Many types of data can be stored as explained in the section on
parameter identifiers. The parameter also has a constituent
specification explained in the constituent array section and possibly
a degree, the meaning of which is model dependent and a bibliographic
reference.
The basic syntax of a parameter is
``identifier'' ( ``phase name'' , ``constituent array'' ; ``degree'' ) ``expression'' ``bibl.ref.''
These parts are explained in more detail below.
\subsubsection{Model Parameter Identifiers}\label{sc:paramid}
The OC thermodynamic package can handle any phase property that depend
on $T, P$ and the constitution of the phase using the models
implemented. It is easy to extend the number of properties by
declaring property identifiers in the source code. If the parameters
should have an influence on the Gibbs energy (like the Curie
temperature) or a diffusion coefficient (like the mobility) the
necessary code to calculate this must be added.
A list of the model parameter identifiers as shown in
Table~\ref{tab:mpis} can be obtained by the command {\bf LIST
MODEL\_PARAM\_ID}
\begin{table}[!h]
\caption{Current set of model parameter identifiers}\label{tab:mpis}
{\small
\begin{verbatim}
Indx Ident T P Specification Status Note
1 G T P 0 Energy
2 TC - P 2 Combined Curie/Neel T
3 BMAG - - 1 Average Bohr magneton numb
4 CTA - P 2 Curie temperature
5 NTA - P 2 Neel temperature
6 IBM - P &<constituent#sublattice> 12 Individual Bohr magneton num
7 THET - P 2 Debye or Einstein temp
8 V0 - - 1 Volume at T0, P0
9 VA T - 4 Thermal expansion
10 VB T P 0 Bulk modulus
11 G2 T P 0 Liquid two state parameter
12 CBT T P 2 Hickel T
13 MQ T P &<constituent#sublattice> 10 LN mobility1 of component
14 MF T P &<constituent#sublattice> 10 LN mobility2 of component
15 MG T P &<constituent#sublattice> 10 LN mobility3 of component
16 THT2 T P 2 Smooth step function T
17 DCP2 T P 2 Smooth step function value
18 VISC T P 0 Viscosity
19 LPX T P 0 Lattice param X axis
20 LPY T P 0 Lattice param Y axis
21 LPZ T P 0 Lattice param Z axis
22 LPTH T P 0 Lattice angle TH
23 EC11 T P 0 Elastic const C11
24 EC12 T P 0 Elastic const C12
25 EC44 T P 0 Elastic const C44
26 FHV T P &<constituent#sublattice> 10 Flory-Huggins volume ratio
27 RHO T P 0 Electrical resistivity
28 LAMB T P 0 Thermal conductivity
29 HMVA T P 0 Enthalpy of vacancy form
30 TSCH - P 2 Schottky anomality T
31 CSCH - P 2 Schottky anomality Cp/R
\end{verbatim}}
\end{table}
Several of these identifiers have no supporting software implemented,
this is an ongoing project. The columns T P indicate if the parameter
may depend on $T$ or $P$. Some identifiers require additional
specification of the constituent and sublattice, like the mobility of
a constituent. Currently it is not yet clear if mobilities should
depend on the sublattice or not but the notation allows that.
A slightly more detailed explanation of the identifiers are:
\begin{itemize}
\item G, the Gibbs energy parameter for an endmember or an
interaction. G(LIQUID,FE;0) is the Gibbs energy for pure liquid Fe.
Note that the parameter will be used also below the melting
temperature of Fe for a liquid phase containing Fe. G(LIQUID,CR,FE;0)
is the regular parameter for Cr and Fe in the liquid.
\item TC, a parameter for the critical temperature for ferro or
antiferro magnetic ordering using the Inden model.
\item BMAG, a parameter for the average Bohr magneton number using
the Inden model.
\item CTA, a parameter for the Curie temperature for ferromagnetic
ordering using a modified Inden model.
\item NTA, a parameter for the Neel temperature for antiferromagnetic
ordering using a modified Inden model.
\item IBM\&C, a parameter for the individual Bohr magneton number for
constituent C using a modified Inden model. For example
IBM\&FE(BCC,FE) is the Bohr magneton number for BCC Fe. The
identifier IBM\&FE(BCC,CR) means the Bohr magneton number of a
single Fe atom in BCC Cr. An identifier IBM\&FE(BCC,CR,FE) can be
used to decribe the composition dependence of the Bohr magneton
number for Fe in BCC.
\item THET, a parameter for the Debye or Einstein temperature.
\item V0, a parameter for the volume at 298.15~K and 1 bar.
\item VA, a parameter for the integrated thermal expansion.
\item VB, a parameter for the Bulk modulus.
\item G2, a parameter for the two-state liquid model.
\item CBT, a parameter for the crystal breakdown T.
\item MQ\&C, a parameter for the logarithm of the frequency factor of
the mobility of constituent C.
\item MF\&C, a parameter for the activition energy of the mobility of
constituent C.
\item MG\&C, a parameter for the magnetic factor of the mobility of
constituent C.
\item THT2, The T for a smooth change of C$_P$
\item DCP2, The value of the smooth change in J/mol
\item VISC, a parameter for the viscosity.
\item LPX, a parameter the lattice parameter in X direction.
\item LPY, a parameter the lattice parameter in Y direction.
\item LPZ, a parameter the lattice parameter in Z direction.
\item LPTH, a parameter the angle between lattice directions.
\item EC11, a parameter for the elastic constant C11.
\item EC12, a parameter for the elastic constant C12.
\item EC44, a parameter for the elastic constant C44.
\item FHV\&C, a parameter for the Flory-Huggins volume ratio of C
\item RHO, a parameter for the electrical resistivity.
\item LAMB, a parameter for the thermal conductivity.
\item HMVA, a parameter for the enthalpy of vacancy formation.
\item TSCH, the T for a Schottky anomality
\item CSCH, the Schottky anomality $\Delta C_P$.
\end{itemize}
The current value of any of these parameter identifiers can be obtaind
by the command {\bf LIST STATE\_VARIABLE} using the identifier and
appropriate phase and component specifiers, see
section~\ref{sc:list_statevar}.
For details of the meaning of the model identifier refer to the model
documentation. As already mentioned many of the identifiers, like the
mobility, does not influence the Gibbs energy but as they depend on
the $T, P$ and constitution of the phase it is convenient to model
them in the same way as the thermodynamic data.
\subsubsection{Constituent array and degrees}
A constituent array specifies one or more constituent in each
sublattice. A constituent must be entered as a species with fixed
stoichiometry. Between constituents in different sublattices you must
give a colon, ":", between interacting constituents in the same
sublattice you must give a comma, "," or a space. A constituent array
with exactly one constituent in each sublattice is also called an
``endmember'' as it give the value for a ``compound'' with fixed
stoichiometry. Constituent arrays with one or more interaction
constituents describe the composition dependence of the property.
Without such parameters the property will vary linearly between the
endmembers.
If there are no sublattices, like in the gas, you just give the phase
and the constituent
G(GAS,C1O2)
If no degree is specified it is assumed to be zero. For endmembers
the degree must be zero but it may sometimes be useful to specify the
zero in order to distinguish the parameter from the expression for the
calculated value of the property, like the chemical potential of a
component. In the gas phase you normally assumes there are no
interactions but it is possible to add such parameters. For an fcc
phase with 4 sublattice for ordering and one for interstitials an
endmember parameter is
G(FCC,AL:NI:NI:NI:VA;0)
This would be the Gibbs energy of an fcc AL1NI3 ordered compound.
An interaction between vacancies and carbon in the austenite is
G(FCC,FE:C,VA;0)
For an interaction parameter you should always specify a degree but
also in this case an omitted degree is interpreted as zero.
\subsubsection{The TPFUN expression and bibliographic reference}\label{sc:tpfun}
The expression for a parameter can be a single value or a function of
$T$ and $P$. It must start with a low temperature limit, usually
298.15~K and must finish with a high temperature limit. These
expressions as well as their first an second derivatives will be
calculated by the TP-fun package. To simplify that there is a strict
syntax for the expression. A term in the expression is
``numeric value'' * ``name of TP function'' *T** ``power'' *P** ``power''
You can construct very complex expression by referring to other
functions. If ``power'' is zero the corresponding *T** or *P** can be
omitted. If it is negative it must be surrounded by parenthesis like
(-1). If it is unity the **1 can be skipped.
Several terms, seperated by signs, forms an expression and it must be
terminated by a semicolon, ``;''. After the semicolon there must be a
high temperature limit or a breakpoint in temperature. A breakpoint
must be followed by the letter ``Y'' and then a new expression for
temperatures above the breakpoint.
{\bf It is the responsability of the database manager to ensure the
expression is continuous at the breakpoint. If there are jumps in
the value at a breakpoint strange things will happen when
calculating equilibria.}
After the high temperature limit the letter ``N'' must be given
followed by a bibliographic reference for the parameter. Use the
commands AMEND or ENTER BIBLIOGRAPHIC to give the reference.
{\bf The database manager should always add a bibliographic reference
even if it is just his or her name and a date. This avoids people
to mistake a value inspired by your experience for a carefully
validated parameter.}
A term can be used inside a natural logarithm, LN, or exponential,
EXP. And the LN or EXP can be multiplied with a term. On the other
hand you are not allowed to have any parenthesis, except around powers
or arguments to LN and EXP. A valid expression is
\begin{verbatim}
298.15 -8856.94+157.48*T-26.908*T*LN(T)+.00189435*T**2
-1.47721E-06*T**3+139250*T**(-1); 2180 Y
-34869.344+344.18*T-50*T*LN(T)-2.88526E+32*T**(-9); 6000 N 91Din
\end{verbatim}
where 91Din is the bibliographic reference to the SGTE unary database.
\subsection{The reference state of a component}
The values of most thermodynamic data must have a defined reference
state. By default the reference state for the components is SER
(Stable Element Reference) which is the stable state of the element at
298.15~K and 1~bar. (NOTE: the default reference state is defined by
the database but today almost all databases have SER as reference
state.)
For each component (also for other components than the elements) you
can specify a phase at a given temperature and pressure as reference
state, see section~\ref{sc:setref}. The phase must exist for the
component as pure.
A state variable like the chemical potential, MU(O), will refer to the
user defined reference state if set. To obtain the value for the SER
state you can use a suffix S, i.e. MUS(O) to obtain the chemical
potential refered to SER. All state variables are listed in
Table~\ref{tab:statev}.
Note that the value of integral properties like Gibbs energy, $G$,
enthalpy, $H$, etc. may have mixed reference states unless all
components have the same phase as reference state. In order to have
the enthalpy of mixing of a phase all components must have that phase
as reference state. For the volume, $V$, SER is always used as
reference state unless all components have the same reference state.
\subsection{Macro files}\label{sc:macro}
The macro command is very useful for preparing complex calculations
and to remember how you did them. A macro file is simplest to create
staring from a log file (created by the {\bf SET LOG} command). See the
macros directory for examples.
After a macro command the popup window will allow you to search for
the file on all your directories unless you type the name of the
file on the same line. In the latter case the macro file must be
on you ``working directory'', see section~\ref{sc:popup}
When you open files, such as databases, inside a macro file and you
type the file name on the same line as the command as ``read tdb
./steel1'', you must prefix the file name, ``steel1'' with ``./'' if
the tdb file is on the same directory as the macro file. If your
command line is just ``read tdb'' the popup window will be activated
and you can specify the file there.
If you open another macro file inside a macro (typically when you do
assessments) you must also prefix the name of the macro with ``./''
unless you want to select the macro using the popup window.
You can insert stops in the macro file with ``@\&'' at the beginning
of a line. This can be useful to inspect the output. The macro
continues after pressing the ENTER/RETURN key. Depending on the
graphical driver you use the program will normally pause after each
plot and you must use the mouse to click on the graphical window to
continue.
You can insert comments in the macro file with ``@\$'' at the beginning
of the comment line.
A macro file should be terminated with the command {\bf SET
INTERACTIVE} which gives back control to the keyboard (or the
calling macro file) otherwise the program may terminate at the end of
the macro.
Macro files can be nested 5 levels deep.
\subsection{Assessment of model parameters}
One of the important uses of the OC software is to assess model
parameters in the phases of a system using experimental and
theoretical data. This is done by recalculating the experimental data
from the model and by varying the model parameters a least square
routine, LMDIF developed at Argonne National Lab in 1981, is used to
find the best set.
Assessments are a very difficult procedure as you must also take into
account the extrapolations of the model outside the range of
experimental data. So called ``First Principles Calculations'' or the
somewhat simpler ``Density Functional Theory'' (DFT) which are based
on the electronic structure of the elements can provide information
for metastable as well as for the stable state. But you must be
careful that the result from such calculations does not represent a
mechanically unstable state with imaginary phonon frequencies.
Experimental data can be direct measurements of thermodynamic data
like enthalpies, chemical potentials, heat capacities, activities, etc
but very important are also measurements of phase diagrams,
solubilities etc because they are also related to the equilibrium
state.
There are several commands related to the assessment procedure in OC
but during the assessment you will also use the basic facilities to
calculate equilibria for different kinds of conditions as well as many
different kinds of diagrams to verify the results.
\subsubsection{Entering coefficients to be assessed}
The command ``enter optimizing coefficients'', see
section~\ref{sc:optcoeff} creates symbols A00 up to A99 that can be
used as coefficients in the thermodynamic model parameters. Maximum
number of coefficients are 100.
\subsubsection{Entering phases and model parameters}
The elements, species and phases with their appropriate models are
entered using the appropriate commands. Normally this is on a macro
file in order to have proper documentation. Keep also in mind that an
assessment is often revised after a few years when new data become
available or you find that the extrapolations of an assessment to a
higher order system is not reasonable.
The model parameters are entered using ``enter parameter'', see
section~\ref{sc:enterparam} or ``enter tpfun'', see
section~\ref{sc:entertpf} as many parameters may share some properties
and a TP-function can be used in several parameters. The optimizing
coefficents A00 to A99 with different T and P dependence can be used
instead of numerical values as their values should be assessed.
\subsubsection{Entering experimental data}
This is done either by entering single equlibria with conditions and
in addition using the command ``enter experiment'', see
section~\ref{sc:enterexp} where the experimental data is given with an
uncertainty. Each equilibrium with an experiment is given a unique
name.
Often there are tables with values and instead of entering each of
them there is a command ``enter many\_equilibria'', see
section~\ref{sc:entermany} with a simplified syntax.
When all equilibria with experiental data has been entered you have to
give the command ``set range'', see section~\ref{sc:setrange} to give
the first and last equilibrium number that should be used in the
assessment. If necessary this range can be extended during the
assessment.
All the experimental data should also be entered as a mcro file to
keep a documentation.
\subsubsection{Saving the state of the assessment}
Any time during an assessment it is possible to save the values of all
assessed parameters and the calculated experimental equilibria by the
command ``save unform {\em filename}'', see section~\ref{sc:saveunf}.
With this command the data inside OC will be written as an unformatted
Fortran file and this can be saved and later read back into the OC
software by the command ``read unfomatted {\em filename}'', see
section~\ref{sc:readunf}. If these commands are inside a macro file
prefix the filename with ``./'' to read and write on the same
directory as the macro file.
These unformatted files are very convenient but beware that they may
not be portable to other operating systems or even other versions of
OC compiled with different Fortran compilers. It may change in future
releases of the OC software. Thus keep printouts and macro files also
if you later want to make modifications.
\subsubsection{Performing the assessment}\label{sc:assess}
There are many decisions to make during the assessment and a general
description how to perform an assessment can be found in the book by
Lukas et al~\cite{07Luk}. It is never possible to try to assess all
parameters using all experiments in a single step. Normally the user
selects different sets of experimental data by the ``set weight''
command, see section~\ref{sc:setw} and fits a few model parameters to
these using the command ``set variable-coeff'', see
section~\ref{sc:setvar}. This can typically an enthalpy of mixing or
a heat capacity function for a compound.
The command to run the least square fit is ``optimize'' followed by
the maximum number of iterations, see section~\ref{sc:optim}. If zero
is given a single loop is made through all equilibria with nonzero
weights within the specified range is made. It is also possible to
use the command ``calculate all'', see section~\ref{sc:calcall}, to
calculate all non-zero weight equilibria. With the latter command you
can turn on the grid minimizer, in the optimize command the grid
minimizer is always turned off.
When the optimize command is given with nonzero maximum there will be
output on the screen at regular intervals giving the current values of
the optimizing coefficients and the value of the sum of squares. When
the oprimization is finished there will also be a listing of the
errors for all experiments.
With the command ``list opt short'', see
section~\ref{sc:listoptshort}, the current values of the optimizing
coefficients and all equiliria with the experimental data is listed
together with the sum of squares. New selection of equilibria or
weights can be made and the values obtained for the optimizing
coefficients must also be reasonable but to know what is reasonable is
not always easy. These steps are repeated until the user is satisfied
or exhausted.
Macro files to calculate and plot of the calculated properties
overlayed with the experimental data should be preoared and run
regularly as just looking at numbers is not sufficient.
At a later stage solubilities and phase diagram data are used but in
many cases reasonable guesses of the start values of model parameters
must be made to be able to calculate the equilibrium with the
experiment. Great care must be taken that the calculated equilibria
for the inital model parameters are reasonably close to the
experimental. Parts of the experimental phase diagram may have to be
assessed separately and the metastable extrapolations of the different
phases checked.
Sometimes a phase appears in a region where it should not be stable
and additional fictitious experimental data may have to be added to
prevent this to happen.
At the end the assessment should be written up and published.
\subsection{Environment and startup macro file}
The OC program will look for an environment variable called OCHOME and
if it finds this it will look for a file start.OCM which will be
executed before the user gets control. This can typically be useful
to set some variables like the plot terminals, see
section~\ref{sc:gnuterm}. If there is no OCHOME environment variable
the ``working directory'' will be searched.
The ochelp.hlp file should be copied to this OCHOME directory.
%If the OCHOME directory has a subdirectory called ``data'' this will
%be searched when the user tries to read a TDB file.
\subsection{User interface feedback}
OC has grown organically and although the basic concepts has been
quite clear the implementations of several of these has become rather
confusing. This will eventually require some cleaning up of the user
interface.
If you like a Graphical User Interface you are welcome to write it.
A central part of any thermodynamic software is the modeling of the
phases. A new PDB format for databases may help a little with the
specification of the models. An attempt has been made in this version
to clean up the way a model is specified and used. At present you
must first ENTER the phase to give a name, basic model, sublattices
and constituents. Then use the AMEND command to add magnetism, a
disordered fraction set and/or use BCC/FCC permutations. Originally
some of these things were set by the command SET PHASE ... BIT and
that was not very clear.
Some computational options like for the grid minimizer are still set
with several different commands. It is useful for the developers to
have some feedback from users to organize this better.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Below is an extract of the OC command interface for version 5
% Comparing this with the current software is be way to know
% where to update the user guide ... hm
%
%F! basic commands
%F character (len=16), dimension(ncbas), parameter :: cbas=&
%F ['AMEND ','CALCULATE ','SET ',&
%F 'ENTER ','EXIT ','LIST ',&
%F 'QUIT ','READ ','SAVE ',&
%F 'HELP ','INFORMATION ','BACK ',&
%F 'NEW ','MACRO ','ABOUT ',&
%F 'DEBUG ','SELECT ','DELETE ',&
%F 'STEP ','MAP ','PLOT ',&
%F 'HPCALC ','FIN ','OPTIMIZE ',&
%F ' ',' ',' ',&
%F ' ',' ',' ']
%F! in French
%F! 'MODIFIEZ ','CALCULEZ ','REGLEZ ',&
%F! 'ENTREZ ','EXIT ','AFFICHER ',&
%F! 'QUIT ','LIRE ','SAUVGARDE ',&
%F! 'AIDEZ ','INFORMATION ','RETURNEZ ',&
%F! 'NOUVEAU ','MACRO ','ABOUT ',&
%F! 'DEBUG ','SELECTIONEZ ','EFFACEZ ',&
%F! 'STEP ','MAP ','DESSINEZ ',&
%F! 'HPCALC ','FIN ',' ']
%F! NOTE a command line can contain options preceeded by /
%F! for example "list /out=myfile.dat all_data" or
%F!-------------------
%F! subcommands to LIST
%F character (len=16), dimension(nclist) :: clist=&
%F ['DATA ','SHORT ','PHASE ',&
%F 'STATE_VARIABLES ','BIBLIOGRAPHY ','MODEL_PARAM_ID ',&
%F 'AXIS ','TPFUN_SYMBOLS ','QUIT ',&
%F 'PARAMETER ','EQUILIBRIA ','RESULTS ',&
%F 'CONDITIONS ','SYMBOLS ','LINE_EQUILIBRIA ',&
%F 'OPTIMIZATION ','MODEL_PARAM_VAL ','ERROR_MESSAGE ',&
%F ' ',' ',' ']
%F!-------------------
%F! subsubcommands to LIST DATA
%F character (len=16), dimension(nlform) :: llform=&
%F ['SCREEN ','TDB ','MACRO ',&
%F 'LATEX ','PDB ',' ']
%F!-------------------
%F! subsubcommands to LIST PHASE
%F character (len=16), dimension(nclph) :: clph=&
%F ['DATA ','CONSTITUTION ','MODEL ',&
%F ' ',' ',' ']
%F!-------------------
%F! subsubcommands to LIST OPTIMIZE results
%F character (len=16), dimension(noptopt) :: optopt=&
%F ['SHORT ','LONG ','COEFFICIENTS ',&
%F 'GRAPHICS ','DEBUG ','MACRO ',&
%F ' ',' ',' ']
%F!-------------------
%F! subcommands to CALCULATE
%F character (len=16), dimension(ncalc) :: ccalc=&
%F ['TPFUN_SYMBOLS ','PHASE ','NO_GLOBAL ',&
%F 'TRANSITION ','QUIT ','GLOBAL_GRIDMIN ',&
%F 'SYMBOL ','EQUILIBRIUM ','ALL_EQUILIBRIA ',&
%F 'WITH_CHECK_AFTER',' ',' ']
%F!-------------------
%F! subcommands to CALCULATE PHASE
%F character (len=16), dimension(nccph) :: ccph=&
%F ['ONLY_G ','G_AND_DGDY ','ALL_DERIVATIVES ',&
%F 'CONSTITUTION_ADJ','DIFFUSION_COEFF ',' ']
%F!-------------------
%F! subcommands to ENTER
%F character (len=16), dimension(ncent) :: center=&
%F ['TPFUN_SYMBOL ','ELEMENT ','SPECIES ',&
%F 'PHASE ','PARAMETER ','BIBLIOGRAPHY ',&
%F 'CONSTITUTION ','EXPERIMENT ','QUIT ',&
%F 'EQUILIBRIUM ','SYMBOL ','OPTIMIZE_COEFF ',&
%F 'COPY_OF_EQUILIB ','COMMENT ','MANY_EQUILIBRIA ',&
%F 'MATERIAL ','PLOT_DATA ','GNUPLOT_TERMINAL',&
%F ' ',' ',' ']
%F!-------------------
%F! subcommands to READ
%F character (len=16), dimension(ncread) :: cread=&
%F ['UNFORMATTED ','TDB ','QUIT ',&
%F 'DIRECT ','PDB ',' ']
%F!-------------------
%F! subcommands to SAVE
%F! note SAVE TDB, MACRO, LATEX part of LIST DATA !!
%F character (len=16), dimension(ncsave) :: csave=&
%F ['TDB ','SOLGASMIX ','QUIT ',&
%F 'DIRECT ','UNFORMATTED ',' ']
%F!-------------------
%F! subcommands to AMEND first level
%F! many of these should be subcommands to PHASE
%F character (len=16), dimension(ncam1) :: cam1=&
%F ['SYMBOL ','ELEMENT ','SPECIES ',&
%F 'PHASE ','PARAMETER ','BIBLIOGRAPHY ',&
%F 'TPFUN_SYMBOL ','CONSTITUTION ','QUIT ',&
%F 'COMPONENTS ','GENERAL ','CP_MODEL ',&
%F 'ALL_OPTIM_COEFF ','EQUILIBRIUM ',' ',&
%F 'LINE ',' ',' ']
%F!-------------------
%F! subsubcommands to AMEND PHASE
%F character (len=16), dimension(ncamph) :: camph=&
%F! ['MAGNETIC_CONTRIB','COMPOSITION_SET ','DISORDERED_FRACS',&
%F ['MAGNETIC_INDEN ','COMPOSITION_SET ','DISORDERED_FRACS',&
%F 'LIQUID_2_STATEML','QUIT ','DEFAULT_CONSTIT ',&
%F 'DEBYE_CP_MODEL ','EINSTEIN_CP_MDL ','XIONG_INDEN_MAGN',&
%F 'ELASTIC_MODEL_1 ','GADDITION ',' ']
%F!-------------------
%F! subcommands to SET
%F character (len=16), dimension(ncset) :: cset=&
%F ['CONDITION ','STATUS ','ADVANCED ',&
%F 'LEVEL ','INTERACTIVE ','REFERENCE_STATE ',&
%F 'QUIT ','ECHO ','PHASE ',&
%F 'UNITS ','LOG_FILE ','WEIGHT ',&
%F 'NUMERIC_OPTIONS ','AXIS ','INPUT_AMOUNTS ',&
%F 'VERBOSE ','AS_START_EQUILIB','BIT ',&
%F 'VARIABLE_COEFF ','SCALED_COEFF ','OPTIMIZING_COND ',&
%F 'RANGE_EXPER_EQU ','FIXED_COEFF ','T_AND_P ']
%F! subsubcommands to SET STATUS
%F character (len=16), dimension(ncstat) :: cstatus=&
%F ['ELEMENT ','SPECIES ','PHASE ',&
%F 'CONSTITUENT ',' ',' ']
%F! 123456789.123456---123456789.123456---123456789.123456
%F! subsubcommands to SET ADVANCED
%F character (len=16), dimension(ncadv) :: cadv=&
%F ['EQUILIB_TRANSF ','QUIT ','EXTRA_PROPERTY ',&
%F 'DENSE_GRID_ONOFF','SMALL_GRID_ONOFF',' ']
%F! 123456789.123456---123456789.123456---123456789.123456
%F! subsubcommands to SET BITS
%F character (len=16), dimension(nsetbit) :: csetbit=&
%F ['EQUILIBRIUM ','GLOBAL ','PHASE ',&
%F ' ',' ',' ']
%F! 123456789.123456---123456789.123456---123456789.123456
%F! subsubcommands to SET PHASE
%F character (len=16), dimension(nsetph) :: csetph=&
%F ['QUIT ','STATUS ','DEFAULT_CONSTIT ',&
%F 'AMOUNT ','BITS ','CONSTITUTION ']
%F! 123456789.123456---123456789.123456---123456789.123456
%F!-------------------
%F! subsubsubcommands to SET PHASE BITS
%F character (len=16), dimension(nsetphbits) :: csetphbits=&
%F ['FCC_PERMUTATIONS','BCC_PERMUTATIONS','IONIC_LIQUID_MDL',&
%F 'AQUEOUS_MODEL ','QUASICHEMICAL ','FCC_CVM_TETRADRN',&
%F 'FACT_QUASICHEMCL','NO_AUTO_COMP_SET','QUIT ',&
%F 'EXTRA_DENSE_GRID','FLORY_HUGGINS ',' ',&
%F ' ',' ',' ']
%F! 123456789.123456---123456789.123456---123456789.123456
%F!-------------------
%F! subcommands to STEP
%F character (len=16), dimension(nstepop) :: cstepop=&
%F ['NORMAL ','SEPARATE ','QUIT ',&
%F 'CONDITIONAL ',' ',' ']
%F! 123456789.123456---123456789.123456---123456789.123456
%F!-------------------
%F! subcommands to DEBUG
%F character (len=16), dimension(ncdebug) :: cdebug=&
%F ['FREE_LISTS ','STOP_ON_ERROR ','ELASTICITY ',&
%F 'TEST1 ','TEST2 ',' ']
%F!-------------------
%F! subcommands to SELECT, maybe some should be CUSTOMMIZE ??
%F character (len=16), dimension(nselect) :: cselect=&
%F ['EQUILIBRIUM ','MINIMIZER ','GRAPHICS ',&
%F 'LANGUAGE ','OPTIMIZER ',' ']
%F!-------------------
%F! subcommands to DELETE
%F character (len=16), dimension(nrej) :: crej=&
%F ['ELEMENTS ','SPECIES ','PHASE ',&
%F 'QUIT ','COMPOSITION_SET ','EQUILIBRIUM ',&
%F 'STEP_MAP_RESULTS',' ',' ']