Getting started
File structure
The package installation directory is structured as follows:
NODA
├───doc
│ ├───_build
│ ├───...
│ └───source
├───noda
│ │ alloy_system.py
│ │ ...
│ └───data
│ fcc-AB-mob-ideal.ods
│ fcc-AB-thermo-ideal.ods
│ fcc-NiCrSi-mob-Du2001.ods
│ fcc-NiCrSi-thermo-Schuster2000.ods
│ user_data.toml
└───tests
│ conftest.py
└───jobs
├───ideal_couple
│ ideal_couple.toml
│ ideal_couple.png
│ run.py
│ run_test.py
├───...
The
docfolder contains the source code of the documentation, and the html files once these are built.The
nodafolder contains the source code of the package and a set of data files used to run test jobs.The
testsfolder contains input files used to run test jobs.
The user directory, whose location is set by the NODA_HOME environment
variable (see Setting the NODA_HOME environment variable) is used to store user data — it is
also typically used to store job folders, although these can be located anywhere
in the file system:
NODA_user
├───data
│ my_thermodynamics_database.ods
│ my_mobility_database.ods
│ user_data.toml
└───jobs
└───fancy_simulation
simulation1.toml
simulation2.toml
make_fancy_graphs.py
Simulations are created from a Python script (for example,
make_fancy_graphs.py) or interactively in a Python interpreter. The
configuration (system properties, simulation conditions) is provided
through an input file with the TOML format (for example,
simulation1.toml) or directly through a Python dictionary. The
contents of the configuration and common use cases are described in
Basic use.
When a simulation is run, if the NODA_HOME environment variable is provided
and a data folder is found in the user directory, Noda will look for data
there. If not, Noda will look for data in the installation directory noda/data
folder.
Note
Users should not modify the files present in the installation directory
noda/data folder. To get started, users may instead copy these files
to the user directory, and modify them there.
Tests and documentation
The tests folder in the installation directory serves several purposes. Test
jobs are used for validation during code development. It is also recommended to
run the test suite after installing to make sure the installation proceeded
properly (see Running tests). When test jobs are run, simulation results
are compared with reference results, including results from analytical
solutions in the cases where these exist. Running simulations requires data —
this is why Noda ships with some example data. Jobs in the tests folder are
always run using the data in the noda/data folder. Test jobs are also used as
examples in the documentation: see Basic use. The data and job files
are a good starting point to prepare your own data and jobs.
As shown above, in addition to an input file and a running script, test job
folders contain a script named run_test.py: this is used as part of the
automatic testing procedure, which relies on the Pytest framework
(https://docs.pytest.org). Some test job folders also contain image files used
in the documentation.
User data
The file “user_data.toml” is a database register. It uses the TOML format and contains five tables:
[thermodynamics]stores thermodynamic database file names.[mobility]does the same for mobility databases.[partial_molar_volume]stores databases of partial molar volumes of pure elements, vacancies and pores.[vacancy_formation_energy]stores databases of vacancy formation energies in pure elements.[default_parameters]stores default values for various parameters.
For example, the “user_data.toml” file included in the installation directory
(noda/data) contains the following:
[thermodynamics]
[thermodynamics.Schuster2000]
# Database for CrNiSi system
# Source: Schuster and Du 2000, https://doi.org/10.1007/s11661-006-0248-y
file = "fcc-NiCrSi-thermo-Schuster2000.ods"
[thermodynamics.AB_thermo_ideal]
# Made-up data for an ideal A-B binary system
file = "fcc-AB-thermo-ideal.ods"
[mobility]
[mobility.Du2001]
# Database for fcc phase of CrNiSi system
# Source: Du and Schuster, "Assessment of Diffusional Mobilities of Cr, Ni, and
# Si in fcc Cr-Ni-Si Alloys", Zeitschrift fur Metallkunde 92 (2001) 28-31
file = "fcc-NiCrSi-mob-Du2001.ods"
[mobility.AB_mob_ideal]
# Made-up data for an ideal A-B binary system
file = "fcc-AB-mob-ideal.ods"
[partial_molar_volume]
# Partial molar volume of pure elements in m3/mol
[partial_molar_volume.Vegard]
# Calculated as atomic mass / density of the pure elements.
Va = "local"
pore = "local"
Al = 9.99e-06
Cr = 7.27e-06
Ni = 6.59e-06
Si = 1.21e-05
[vacancy_formation_energy]
# Vacancy formation energy in pure elements
# GfV = HfV - T*SfV with [HfV, SfV] in [J/mol, J/mol/K]
[vacancy_formation_energy.Shang2016]
# Source: Shang et al 2016, https://doi.org/10.1016/j.actamat.2016.02.031,
# supplementary materials, xls sheet
# All in fcc phase
Ni = [1.610e+5, 3.469e+1]
Cr = [1.622e+5, 2.342e+1]
Fe = [2.338e+5, 6.055e+1]
Al = [7.082e+4, 3.091e+1]
[default_parameters]
# Used if no database is specified in configuration, or if an element is not
# included in the specified database.
partial_molar_volume = 1e-5 # Partial molar volume in m3/mol
vacancy_formation_energy = [2e5, 50] # Vacancy formation enthalpy and entropy in [J/mol, J/mol/K]
The [thermodynamics] and [mobility] tables associate database names with
the names of the files containing the actual data. These files
should be located in the user data folder. When setting up a simulation, users
may provide one of these database names or directly indicate a file path (see
Setting up a simulation). The content of the database files is described next
(Thermodynamic and mobility database files).
The [molar_volume] and [vacancy_formation_energy] tables associate
database names with partial molar volume and vacancy formation energy data.
When setting up a simulation, users may provide one of these database names, or
directly provide data (see Setting up a simulation). The program looks
for the partial molar volume of all components in the provided database. If a
component is not present, it falls back to a system-wide default value. Here,
if using the Vegard database, Al, Cr, Ni and Si will be
assigned the indicated partial molar volumes, and any other constituent will be
assigned the system-wide default. The vacancy_formation_energy table works
the same way as the molar_volume table, with a slightly different syntax:
the crystal structure of the pure metals is specified, and the energy values
are given as [H, S] lists (in [J/mol, J/mol/K]). The vacancy
formation energy in element A is calculated as
\(G_\mathrm{f}^\mathrm{A} = H_\mathrm{f}^\mathrm{A} - TS_\mathrm{f}^\mathrm{A}\)
. The values are then used to calculate chemical potentials, see Thermodynamics of the metal phase.
Note
Partial molar volumes of pure metals are numerical values. Vacancies and
pores are special in that their partial molar volume can be a float or the
string local, in which case they take the local average molar volume —
see Background.
Factory default values for a number of parameters are provided in the package
files (in the constants module). These can be overridden by specifying
values in the [default_parameters] table, see Default parameters.
Thermodynamic and mobility database files
Thermodynamic and mobility database files are spreadsheets in csv, ods or xlsx format.
The Gibbs free energy of the metal phase is described with the Calphad method, using a Redlich-Kister polynomial for the excess term (see the Thermodynamics of the metal phase Section). Thermodynamic database files in ods and xlsx format contain two sheets:
Elements stores coefficients that describe the temperature dependence of the Gibbs free energy of pure elements, in the form \(G - H_\mathrm{SER}\), according to [Dinsdale_1991]:
\[G = a + b\,T + c\,T\,\ln{T} + d_2\,T^2 + d_3\,T^3 + \frac{e}{T} + G_\mathrm{mag}\](for the magnetic part \(G_\mathrm{mag}\), see [Dinsdale_1991]).
Interactions stores coefficients that describe the temperature dependence of the binary and ternary interaction parameters, in the form:
\[\begin{split}_{}^{0}\Lambda_{ij} = a + b \cdot T,\\ _{}^{1}\Lambda_{ij} = c + d \cdot T,\\ \Lambda_{ijk} = a + b \cdot T.\end{split}\]
Note
Noda only considers ternary interactions of order 0. Entries for coefficients c and d of a ternary endmember will be ignored.
Thermodynamic database files in csv format store the parameters under Elements and Interactions headings.
The logarithm of tracer diffusion coefficients is described with a Redlich-Kister polynomial (see Mobility). Mobility database files contain coefficients that describe the temperature dependence of unary terms, and binary and ternary interaction parameters:
In this context, solute is the diffusing species, while solvent is the endmember in which it diffuses, or the subsystem that generates interactions. For instance, in a Ni-Cr-Al system, there are three solutes (Ni, Cr, Al), three endmembers (Ni, Cr, Al), three binary subsystems (NiCr, NiAl, CrAl) and one ternary subsystem (NiCrAl).
The parameters that populate the thermodynamics and mobility database files
are typically found in journal articles. Users are recommended to use the
files provided in the noda/data folder of the installation directory as
examples to build their own database files.
References