Getting started with OpenCalphad

Bo Sundman, partially updated August 25, 2019

Opencalphad (OC) is a free software with GNU GPL license. The last version is available
at the following web site:
http://www.opencalphad.org or the
A development version is available at the opencalphad repository at::
http://www.github.com/sundmanbo/opencalphad
You can contact me at: bo.sundman@gmail.com

Please be aware that this software is under development. Your

feedback about problems and errors is important to make it better.
But if you have problems with the installation please contact a local
expert.
OC cannot replace your favorite thermodynamic software today or tomorrow but the main
advantage is that you have access to the source code and can (with some efforts) add or fix
things yourself that you are missing in your favorite software.
There are several papers describing OC:

• OpenCalphad - a free thermodynamic software, Bo Sundman, Ursula R Kattner, Mauro

Palumbo and Suzana G Fries (Open Access) Integrating Materials and Manufacturing
Innovation (2015) 4:1

• The implementation of an algorithm to calculate thermodynamic equilibria for multi-

component systems with non-ideal phases in a free software, Bo Sundman, Xiao-Gang
Lu and Hiroshi Ohtani, Computational Materials Science, 101 (2015) 127-137.

• The OpenCalphad thermodynamic software interface, Bo Sundman, Ursula R Kattner,

Christophe Sigli, Matthias Stratmann, Romain Le Tellier, Mauro Palumbo and Suzana
G Fries, Comp Mat Sci, 125 (2016) 188-196

1
1 Documentation
There is an extensive documentation provided with the software. A log of all changes since
2016 is in the file changes.txt on the top directory. The other files you can find:

• in the directory installation/

– Install-OC-Windows-MinGW on Windows using MinGW.

– Install-OC-Windows-Cygwin on Windows using Cygwin (in French).
– Install-OC-Linux-or-macOS on Linux or macOS using GNU.
– Install-help-popup for the online help using browser
– after-installation some advice

• in the directory manual/

– ochelp.html needed for online help, must be copied to your OCHOME directoty.

• in the directory documentation/

– assess.pdf about assessments using OC (draft).

– Getting-started.pdf with OpenCalphad (this document).
– gtp3.pdf, General Thermodynamic Package describing the model package.
– hms3.pdf, Hillert’s Minimizer describing the equilibrium calculations.
– smp2.pdf, StepMapPlot describing calculation and plotting of diagrams (draft).
– ocasi.pdf, OC Application Software Interface (draft).
– oc-macros.pdf, examples how to use OC.
– news-OCi.pdf about added features over the years.
– Possibly some lectures presenting OC.

2 General information
There is no automatic installation routine for OC, you must download and compile the soft-
ware yourself. To do that you may also have to install Fortran compilers and the GNUPLOT
software if you do not already have them. The OC development team cannot offer you any
help for that, please ask some local experts if you need help.

• The code is written in the new Fortran standard and requires a compiler like GNU
Fortran 4.8 or similar.

2
 • The last release of the source code can be found as a zip file on http:://www.opencalphad.org.
The last development version can be obtained as a zip file at the opencalphad repository
on the http://www.github.com. On that site there is also a wiki for information,
discussion and questions.

• See the special installation guides for advice on the installation. If you have problems
please contact a local expert. This is all free software and we are not experts on
hardware.

• If you have access to several CPUs you can test OC with parallelization using Open
MP.

• In the “macro” directory there are examples for a variety of calculations.

• The TQ4lib directory has examples for using the software interface for Fortran and
C/C++.

• Contributions of new and improved source code are welcome. You can do this by
cloning the github repository. Contact Bo Sundman if you want to know more.

3 Some short hints to the user interface

See also news-OC and user guid (UG). The information in these (as well as this) files are
not always up-to-date. You are welcome to inform me about errors and inconsistencies. If
you do not like the current user interface you are welcome to develop your own.

3.1 Opening files with popup window

From version 5.018 I have added creating a popup window when opening 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 how to edit you macro files that you should be
aware of.
You can turn off the open file popup window feature with the command set advanced popup.
You can turn it on again with the same command.

• 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 @pwd inside OC). On a Windows system you can see the working directory
and its files if you type @dir inside OC.

• When the popup window is opened the directories and files matching the “filter” in the
working directory are listed. The filter when open a macro file is “OCM” and when

3
 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.

• 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 read tdb the popup window will open
so you can specify the file in this window.

• But normally you know which database you want to use inside the macro and if you
give the file name on the same line: 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. 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 and prefix “../” by this directory.

• In the macro file you can give the full path to the file to be opended but that is rather
clumsy.

• 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.

• 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”. (I forgot
this in 5.018 so it will be available from 5.019 or later.)

You are welcome to provide feedback on this popup feature.

3.2 Entering and manipulating thermodynamic data

In this and the following sections you can find a brief and unstructured summary how to use
OC and of the commands that may be useful.

• Thermodynamic data can be read from an unencrypted TDB file read tdb “filename”
or entered interactively, see the enter commands. You can specify which elements you
want from the TDB file but not select the phases. Phases you do not want you can
suspend from the calculations with the command set status phase ... = suspend.
If you already have data in the program and want to read new thermodynamic data
from a file you must first remove the old data. You can remove all the thermodynamic
data in the program by the command new YES.

4
 • There are some exception from how data are entered into OC compared to Thermo-
Calc, most important perhaps the “partitioning” of a phase into an ordered and disor-
dered part. OC has implemented this in a different way and it is sometimes necessary
to edit the TDB file before reading such partitioned data from a TDB file.

• You can save the thermodynamic data and results from a calculation (but not STEP
and MAP results) on an unformatted file save UNFORM “filename” and read it back
into the program with read UNFORM “filename”. But beware the format may change
with a future release! The unformatted files may not be compatible with a computer
with another operating system.

• You can save the thermodynamic data using the TDB format by a command
list data TDB filename. The TDB format used by OC can, with some exceptions, be
read also by other thermodynamic software which accepts TDB format.

• You can list the thermodynamic data on the screen with the list data command. You
can list on a file by using the switch list /output=filename .... If you want to write a
TDB file use the command list data TDB.

• You can enter thermodynamic data from a macro file as well as commands for calcula-
tions. In order to document errors or problems please send a complete macro file with
data and commands reproducing the error to Bo.Sundman@gmail.com
You can generate a macro file interactively by setting a log file set log “filename” and
then (after some editing) use the log file as a macro with the extension OCM. The log
file has the extension LOG.

3.3 Setting conditions

• To calculate you must set conditions on the external variables like temperature, T,
pressure, P etc. The number of conditions must be equal to the number of components
plus 2 (Gibbs phase rule).

• Setting conditions is similar to the Thermo-Calc software. Each condition is set sep-
arately by the command is set cond “state variable” = “value”. The safest set of
conditions for calculating an equilibrium, i.e. which has most chance to converge, is to
set values on T, P and N(element), i.e. the total amount of each element. The table
at the end gives a list of available state variable symbols and their meaning.

• It is also possible to set conditions on chemical potentials, activities, enthalpies, vol-

umes and that a phase is stable (fix). See the macro file examples how this is done.
Note that some commands are fragile and they may also change between releases of
the OC software, depending on new ideas and suggestions by users.

5
 • The intention is that you should be able to combine any set of conditions to calculate
the equilibrium, i.e. you should be able to combine conditions on mole fractions,
mass fractions, fix phases, chemical potentials, enthalpies etc. For conditions on mole
fractions you can also enter expressions as conditions, for example to calculate the
congruent melting of UO2 you can set a condition x(liq,o)-x(c1 mo2,o)=0 (see macro
map4.OCM).
• For users with FactSage background there is a command set input amount which allows
the user to set the overall composition by specifying the amount of moles of different
species in the system. The software converts this to conditions on the amounts of the
components.
• You can only use components to set conditions on the amounts, activities and chemical
potential. By default the components are the same as the elements but with the com-
mand amend components you can specify any orthogonal set of species as components.
Beware that with other components than the elements your mole fractions and amounts
of phases may be negative or larger than unity.

3.4 Calculation
• The command calculate equilibrium, which can be abbreviated c e, tries to calculate
the equilibrium. As the minimizer needs a guess of stable phases and their start
constitution, the OC software tries first to invoke a global grid minimizer to find
such a guess. The grid minimizer requires that the conditions are T, P and overall
composition (N, B, x or w).
• If you want to provide yourself a guess of the set of stable phases and constitutions
you can use the amend const phase “name” “amount” “constitution” · · · followed by
the command calculate no global, abbreviated c n.
• The grid minimizer that calculates start points for the general minimizer is powerful
but a bit primitive. If you have ideas how to improve it you are welcome to provide
advice or code. There is a command to have a denser grid (about 10 times more grid
points) using the command set advanced dense
• You should always check the results with you favorite thermodynamic software. Please
give documented feedback on any differences.
• If the calculation does not converge directly try to use the command “c n” two or more
times to continue to iterate from the set of phases you have. The “c e” command will
run the grid minimizer and, therefore, will normally give the same result each time.
• You can also try to change the number of iterations and convergence criteria with the
command set num “max iterations” “convergce criteria”. Default values of these are
500 and 10−6 .

6
• If everything fails try to simplify the conditions for a first calculation. The simplest
are values of T, P and N (component). When that has converged change the conditions
one by one to those you are interested in and for each change calculate without the
grid minimizer, i.e. using “c n”. Calculations at temperatures and compositions where
the system is single phase have a higher chance of success. The algorithm to change
the set of stable phases is fragile and is still being fine-tuned.

• Phases with miscibility gaps can be a problem. The grid minimizer should detect such
and automatically add new composition sets for phases that can be stable with two
different compositions. Composition sets created automatically have the suffix AUTO.

• The user can also add composition sets manually with the command
amend phase “name” comp set . You can add a prefix and suffix (max 4 letters) to the
phase name (for example the cubic carbide treated as a composition set to the FCC
phase can have the prefix MC so the full name is MC FCC.
Composition sets have a number after the phase name preceded by the letter #, like
LIQUID#2. The user can use both pre- and suffixes or use the composition set number
to specify the composition set. A phase can have up to 9 composition sets.

• When entering a composition set manually you are asked for a min or max values
of each constituent. After a calculation the software will try to match a calculated
constitution of a phase which has several composition sets to the set with the closest
default constitution.

• To set the default constitution of the first composition set use set phase “name” de-
fault constitution · · · .

• There are several options to calculate things:

– calculate all calculates all equilibria set by the set range command. It is intended
for equilibria with experiments and used in assessments but can be used to cal-
culate a range of equilibria not suitable for the STEP command.
– calculate global gridmin will use the global gridminimizer and not the final itera-
tive routine,
– calculate phase to calculate properties for a specific phase. You must first specify
the amount of the phase and if you want to use the current constitution. Then
you can select
∗ only G to get G and derivatives with respect to T .
∗ G and dGdy to get G and also first derivatives w.r.t. constituents.
∗ all derivatives to get G and all first and second derivatives w.r.t T , P and
constituents.
∗ constitution adjustment This will ask for a new composition (default is the
current or the one specified) and miminize the Gibbs energy of the specified

7
 phase to have the equilibrium constitution (for example adjust the fraction
of gas constituents or sublattice fractions). It will return the value of G and
all chemical potentials (divided by RT).
∗ diffusion coeff This will also ask for a new composition and return the values
of the Darken stability matrix calculated as ∂G A
∂NB
and if the phase has any
mobility data also their values.
– calculate symbol will calculate the value of one or more symbols.
– calculate tp funs will calculate the value and the first and second derivatives with
respect to T and P for all tp functions (used for the model parameters).
– calculate transition “phase” “condition” calculates the value of the “condition”
when the phase is just stable, for example the melting T if the “phase” is LIQUID.

3.5 Setting the status of phases: entered, fixed, dormant, sus-

pended
To set the status of a phase to be fixed is treated as a condition.

• By default all phases have the status ENTERED. You can suspend phases you do not
want by set status phase “name” · · · = “suspend”.
If the phase should be stable you will calculate a metastable equilibrium.
• To specify that a phase must be stable you can set its status to fix, the command is
set status phase “name” = “fix” ”amount”.
If the amount is set to zero OC will calculate a point on the solubility line of the phase.
Note it may fail because there is no such point due to the other conditions.
• The dormant status means the phase cannot be stable but its driving force is calcu-
lated. If this is positive the phase wants to be stable and the calculated equilibrium is
metastable.

3.6 Listing many things

Most listing are written on the screen but when output obviously should be written on a file
the program will ask for a file name. If you want the output from other listings to be written
on a file you can use the switch /output=filename or /append=filename directly after the
first command. For example list /out=result r,,,. The extension of the output file will be
DAT. The output file will be reset to the screen after each command.
There is also a SAVE command mainly intended for saving on a file. For example save tdb
filename will write all the thermodynamic data in the OC TDB format on the file with the
extension TDB. This can be read back later as a TDB file.

8
• Listing results after a calculation is done by list result “option”. This is the default
list and can be abbreviated l,,. This list will always include the current conditions and
some global results and one line for each component. The options are at present:

– 1 list of stable phases with amount and composition in mole fractions in value
order.
– 2 list of stable phases with amount, composition and constitution in mole fractions
in value order.
– 3 list of stable phases with amount and composition in mole fractions in alpha-
betical order.
– 4 list of stable phases with amount and composition in mass fractions in value
order.
– 5 list of stable phases with amount and composition in mass fractions in alpha-
betical order.
– 6 list of stable phases with amount and composition in mass fractions and the
constitution in value order.
– 7 list of all phases with amount and composition in mass fractions in value order.
– 8 list of all phases with amount and composition in mole fractions and constitution
in alphabetical order.
– 9 list of all phases with amount and composition in mole fractions and constitution
in value order.

• The list short A gives one line for each component, species and phase. In this list you
may note the use of the “phase tuple” to indicate composition sets. A phase tuple
has two values, one is the phase number, the other the composition set number. The
first composition set of a phase has the same tuple number as the phase number. As
composition sets can be added and deleted the tuple number of a higher composition
set may change.

• The list short P gives one line for each phase, separated in stable, entered and dormant,
listed in order of increasing instability (driving force).

• The list bibliography list all or a single bibliographic reference. Bibliographic references
are entered when entering parameters. The amend biblio allows interacting amending
of the bibliographic item.

• The list data screen lists all thermodynamic data with bibliographic references. Note
this output is not the TDB format.

• The list equilibria list all entered equilibria (not any results). By default there is only
one equilibrium but during step and map each node point is entered as an equilibria.
The user can also enter equilibria manually.

9
 • The list model param id list all symbols for which one can enter parameters. By default
the G is Gibbs energy, TC the combined Curie and Neel temperature etc.

• The list phase has several options to list various data for a phase.

• The list state variables lists individual values of state variables. The wildcard character
“*” can be used for “all”. Terminate with an empty line.

• The list symbols list the symbols and their expressions. There two predefined symbols,
R and RT. The user can enter any number of additional symbols as functions of state
variables or other symbols. To calculate (and list) the value of a symbol use c sym.

• The list tp symb lists the functions entered for the model parameters. To calculate
their current values use c tp.

3.7 Calculating and plotting diagrams

This part is unfinished and very rudimentary.

• You can calculate property diagram (one independent axis variable) or phase diagrams
(two or more independent axis variables). The command to set an independent axis is
set axis 1 “state variable” “min value” “max value” “increment”. The state variable
used must be a condition. Axis 1 and 2 are implemented.

• With one axis the step command will step from the current equilibrium to the max
and min axis values.

• With two axis the command map will follow “zero phase fraction” (ZPF) lines within
the limits of the axis by replacing one of the axis condition with a phase fix with zero
amount. In this way phase diagrams for any number of components can be calculated.
While following such a line other phases may become stable or disappear and this
generates a node point where several lines meet.

• Plotting of diagrams relies on GNUPLOT, a free software you can install from the
web. The command plot asks for two axis variables and generates pairs of values from
the results calculated by step or map commands.
There are several options to the plot command that are demonstrated by the macro
files.

• Macro files are easily created by using a log file while running OC interactively. On
the log file all input (as well as default values) are written. Then you can edit this and
finish it with the set interactive command to give command back to the keyboard.
When you report problems or errors always sent a macro file that reproduces the error.
Please try to find the simplest case that contains the error.

10
4 GNUPLOT graphics
OC uses the free GNUPLOT software to plot on the screen and other devices. You must
install GNUPLOT before you can obtain any figures.
You can find GNUPLOT at http://gnuplot.info/download.html
In OC you can list or enter a GNUPLOT terminal by the command:
—>OC5: enter gnuplot term

GNUPLOT terminals are: 5

1 SCREEN > set terminal wxt size 900,600
2 PS > set terminal postscript color solid fontscale 0.8
3 PDF > set terminal pdf color solid size 6,4 enhanced fontscale 0.45
4 GIF > set terminal gif enhanced fontscale 0.7
5 PNG > set terminal png enhanced fontscale 0.7
Enter or change a GNUPLOT termial
Terminal id (8 chars):

The terminals listed above are the default on Windows. On a Linux system they may be
different. Before changing anything you should first start GNUPLOT and use the command
“set term” to list the available terminals on your installation of GNUPLOT.
In OC after giving a PLOT command and specified your axis you can select to plot on any
of the the terminal devices listed above (or which you defined yourself) by:
Options? /RENDER/: graphics format n
where the number “n” is the gnuplot terminal you wish to use. If you wish to plot on
SCREEN you do not need to give this command.

5 A summary of state variables.

The state variables are very important for setting conditions and listings. Those recognized
by OC are given in table 1.
The state variables in the user interface have their common symbols, T for temperature,
P for pressure, N for the total amount of moles, “N (element)” for the amount of moles of a
component, “X(element)” for the mole fraction “M U (element)” for the chemical potential,
“AC(element)” for the activity. The symbol B is used for the total mass (copied from the
Thermo-Calc software), “B(element)” for the mass of an element and “W (element)” for the
mass fraction. There are many more state variables like H, G etc, see the table, but not all
of them can be used as conditions.

11
Table 1: A very preliminary table with the state variables and their internal representation.
Some model parameter identifiers are also included. The suffix “z” in Sz etc is the optional
normalizing letter M, W, V or F. The suffix S can also be used to indicate SER as reference
state. The “phase” index for MU etc can be used to specify the reference state.
Symbol Id Index Normalizing Meaning
1 2 suffix
Intensive properties
T 1 - - - Temperature
P 2 - - - Pressure
MU 3 component -/phase - Chemical potential
AC 4 component -/phase - Activity
LNAC 5 component -/phase - LN(activity)=MU/RT
Extensive and normalized properties
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 m3
UF 14 phase#set - F Internal energy per formula unit
Sz 2z -/phase#set - M/W/V/F entropy
Vz 3z -/phase#set - M/W/V/F volume
Hz 4z -/phase#set - M/W/V/F enthalpy
Az 5z -/phase#set - M/W/V/F Helmholtz energy
Gz 6z -/phase#set - M/W/V/F Gibbs energy
NPz 7z phase#set - M/W/V/F Moles of phase
BPz 8z phase#set - M/W/V/F Mass of phase
Qz 9z phase#set - M/W/V/F Stability of phase
DGz 10z phase#set - M/W/V/F Driving force of phase
Nz 11z comp/phase#set -/comp - Moles of component
X 111 comp/phase#set -/comp 0 Mole fraction
X% 111 comp/phase#set -/comp 100 Mole per cent
Bz 12z comp/phase#set -/comp - Mass of component
W 122 comp/phase#set -/comp 0 Mass fraction
W% 122 comp/phase#set -/comp 100 Mass per cent
Y 130 phase#set const#subl - Constituent fraction
Some model parameter identifiers
TC - phase#set - - Curie temperature
BMAG - phase#set - - Aver. Bohr magneton number
MQ&X - phase#set component X - Mobility of X
THET - phase#set - - Debye temperature

6 Phase status
You can specify that a phases should be stable by the command set status phase · · ·. For
example to calculate the melting point of an
12 alloy after specifying the composition and
making a calculation at fixed T and P, you can give the commands set cond T=none; set
status liquid=fix 0; c n. (The commands must be given on separate lines). You can also use
the command calculate transition · · ·.

7 Manipulating the source code

The OC software is provided with a GNU license which means that you have the source
code and can use it and modify it as you wish as long as you do not try to make money of
it. If you want to include the OC software in a commercial program you must contact the
copyright owners.
There is a fairly extensive documentation of the source code in the directory “documen-
tation” and if you look at the code itself there are some comments there too. I have spent
a lot of effort to make the data structures general and flexible to handle multicomponent
and multiphase systems. But there was quite a lot of redundancy introduced during the
development that eventually will be removed.
The set of subroutines is less structured and one problem has been that this code was my
first attempt to use the new Fortran standard so there are probably many things that can
be made simpler. You are welcome to point out where this can be done.

8 Application software library, OCASI, iso-C compat-

ible
There is an OC Application Software Interface (OCASI) following the TQ standard to make
it possible to use OC from application programs. The subroutines in this interface can be
found in the directory “TQ4lib” together with a few test program. Read the separate readme
files in these directories to compile and run these.
There is a Fortran version of the TQ library and also an iso-C version that can be called
from C++/C routines. The isoC binding makes it possible to access data directly from the
data structures defined inside the OC software. There are some test programs for this also.
Use only subroutines in the TQ library to access the OC software, do not call directly
subroutines inside the OC code as they may not be available or have different functionality
in a future release. If you miss some routines please sent a message or discuss this on the
github wiki.

13
9 Parallelization
The code has been developed with parallelization in mind and I have now started to test this
code and surprisingly it seems to work quite well. There is a macro parallel2.OCM showing
a calculation of 400 different equilibria in a 6 component alloy. They need to be initialized
which makes me a bit suspicious but testing changing some and calculate again seems to
work. I have tested on a PC with 4 CPU and 8 threads and the clock time is about 3.5 times
faster compared to calculate them sequentially.
Parallelization can be implemented in several levels in OC, for example the grid minimizer
or even inverting the phase matrix, but the ability to calculate many separate equilibria
in parallel is a key feature to implement full thermodynamic calculations for simulations of
phase transformations using phase field and similar techniques.

Have fun and help make OC useful!

14