data_io

Load thermodynamics and mobility data.

data_io.get_user_data(data_dir, logger)[source]

Get user data from ‘user_data.toml’ file.

If ‘user_data.toml’ file is not found in the user data folder, use the package-provided file instead.

Parameters:
Returns:

res – Content of file.

Return type:

dict

data_io.get_partial_molar_volume(databases, db_register, comps, default, logger)[source]

Get partial molar volumes from specified database.

User input can be a database name, which must be present in the database register, or directly a dict with pure elements as keys. If no partial molar volume database is specified, or if the specified database contains no value for an element, use the default value (see simu.get_user_data()).

Parameters:

  • databases (dict) – Databases in input configuration.

  • db_register (dict) – Molar volume databases in ‘user_data.toml’.

  • comps (list of str) – System components.

  • default – Default value.

  • logger (log_utils.CustomLogger) – Logger.

Raises:

utils.UserInputError – If database entry is formatted incorrectly.

Returns:

res – {k: V_k for k in comps}

Return type:

dict

data_io.get_vacancy_formation_energy(databases, db_register, comps, default, logger)[source]

Get vacancy formation energy in pure elements.

User input can be a database name, which must be present in the database register, or directly a dict with pure elements as keys. If no vacancy formation energy database is specified, or if the specified database contains no value for an element, use the default value (see simu.get_user_data()).

Parameters:

  • databases (dict) – Databases in input configuration.

  • db_register (dict) – Vacancy formation energy databases in ‘user_data.toml’ file.

  • comps (list of str) – System components.

  • default – Default values.

  • logger (log_utils.CustomLogger) – Logger.

Raises:

utils.UserInputError – If database entry is formatted incorrectly.

Returns:

res – {k: [enthalpy, entropy] for k in comps}

Return type:

dict

data_io.get_database(key, databases, db_register)[source]

Get database name and database as a dictionary.

  • If user input is a dict : return this dict

  • If user input is a database name : get the database from registered databases

  • If no user input : return empty dict

Parameters:

  • key (str) – Database type, either ‘partial_molar_volume’ or ‘vacancy_formation_energy’.

  • databases (dict) – Databases provided in input configuration.

  • db_register (dict) – Databases registered in ‘user_data.toml’.

Returns:

  • name (str) – Name of database.

  • dct (dict) – Database parameters as a dict.

Raises:

utils.UserInputError – If database is not found in ‘user_data.toml’.

data_io.get_thermo_from_file(fpath, phase, comps, TK, logger)[source]

Get parameters needed to calculate Gibbs free energy from database file.

Data retrieved from csv or spreadsheet file.

Parameters:

  • fpath (pathlib.Path) – Path of file with thermodynamic database.

  • phase (str) – Name of metal phase.

  • comps (list of str) – System components.

  • TK (float) – Temperature in Kelvin.

  • logger (log_utils.CustomLogger) – Logger.

Raises:
Returns:

p – Thermodynamic parameters arranged as follows:

A: G_A for A in endmembers
AB: [L0, L1] for AB in binary subsystems
ABC: [L0, L1] for ABC in ternary subsystems

Return type:

dict of floats

data_io.get_thermo_from_csv(fpath, comps)[source]

Get thermodynamic parameters from csv file.

Parameters:

  • fpath (pathlib.Path) – Path of file with thermodynamic database.

  • comps (list of str) – System components.

Returns:

dct – Thermodynamic parameters,

'Elements': parameters related to pure elements
'Interactions' : interactions parameters

Return type:

dict of pd.DataFrames

data_io.get_thermo_from_spreadsheet(fpath)[source]

Get thermodynamic parameters from spreadsheet file.

File in ods, xls or xlsx format. Requires an external dependency:

format

package name

xls

xlrd

xlsx

openpyxl

ods

odfpy
Parameters:

fpath (pathlib.Path) – Path of file with thermodynamic database.

Returns:

dct – Thermodynamic parameters,

'Elements': parameters related to pure elements
'Interactions' : interactions parameters

Return type:

dict of pd.DataFrames

data_io.process_elements_parameters(df, comps, TK, phase)[source]

Compute Gibbs free energy of endmembers at a given temperature.

Data is in the form of G - H_SER. See Dinsdale 1991 [1].

Parameters:
Returns:

Thermodynamic parameters,

A: G_A for A in endmembers

Return type:

dict

data_io.process_interaction_parameters(df, comps, logger)[source]

Process interaction parameters.

The parameters belong to the following categories (variables) depending on the quantity they are related to:

  • L : Gibbs free energy

  • Tc : critical temperature

  • beta : magnetism

The parameters correspond to:

  • binary interactions (orders 0 and 1)

  • ternary interactions (order 0, with L1 = 0 for compatibility)

They are given as:

  • order 0: A and B in L0 = a + b*T

  • order 1: C and D in L1 = c + d*T

If a variable is not included in the input file, all parameters are set to 0 for this variable.

Parameters:
Returns:

di – Thermodynamic interaction parameters,

{var: subdi for var in ['L', 'Tc', 'beta']}

where subdi is result of unit_process_interactions().

Return type:

dict

data_io.unit_process_interactions(df, solvents, logger)[source]

Process dataframe with thermodynamic interaction parameters.

Apply sanitary checks and convert from dataframe to dict. For each subsystem in solvents, operation depends on number of matching keys in the dataframe:

  • if 0, set all interaction parameters to 0

  • if 1, get interaction parameters

  • if more than 1, raise exception.

Parameters:

  • df (dataframe) –

    Thermodynamic interaction parameters for one variable. Columns:

    • variable : either of L, Tc or beta (see process_interaction_parameters()).

    • solvent : constituents of subsystem concatenated to string.

    • a, b, c, d : interaction parameters, with

      • order 0 = a + b*T

      • order 1 = c + d*T

  • fpath (pathlib.Path) – Path of file with thermodynamic database.

  • solvents (list of str) – Binary and ternary subsystems, concatenated to strings.

  • logger (log_utils.CustomLogger) – Logger.

Raises:

utils.UserInputError – If several equivalent subsystems (ie permutations of the same subsystem) are present in the database.

Returns:

di_reduced – Thermodynamic interaction parameters,

{k: {letter: val for letter in 'abcd'} for k in solvents}.

Return type:

dict of dicts

data_io.make_L_isotherm(L, T)[source]

Evaluate interaction parameters at given temperature.

Parameters:

  • L (dict) –

    Interaction parameters,

    {k: {letter: val for letter in 'abcd'} for k in solvents}.

  • T (float or int) – Temperature in Kelvin.

Returns:

res – Interaction parameters, {k: [L0, L1] for k in solvents}.

Return type:

dict of lists

data_io.get_mob_from_file(fpath, comps, TK, logger)[source]

Get mobility parameters from input file.

File formats currently supported:

  • xls, xlsx or ods: database from literature

  • json: database from OPTIMOB.

Parameters:

  • fpath (pathlib.Path) – Path of file with mobility database.

  • comps (list of str) – System components.

  • TK (float) – Temperature in Kelvin.

  • logger (log_utils.CustomLogger) – Logger.

Raises:

Exception – If file is not found or file format not accepted.

Returns:

p – {i: subdict for i in comps}

subdict: {j: val for j in subsystems}.

Return type:

dict of dicts

data_io.get_mob_from_spreadsheet(fpath, comps, TK)[source]

Get mobility parameters.

Data retrieved from csv or spreadsheet file. The latter requires an external dependency:

format

package name

xls

xlrd

xlsx

openpyxl

ods

odfpy
Parameters:

  • fpath (pathlib.Path) – Path of file with mobility database.

  • comps (list of str) – System components.

  • TK (float) – Temperature in Kelvin.

Returns:

p – {i: subdict for i in comps}

subdict: {j: L0 for j in subsystems}

Return type:

dict of dicts

data_io.get_mob_from_json(fpath, comps, TK)[source]

Get mobility parameters from json file.

Parameters:

  • fpath (pathlib.Path) – Path of file with mobility database.

  • comps (list of str) – System components.

  • TK (float) – Temperature in Kelvin.

Returns:

p – {i: subdict for i in comps}

subdict: {j: L0 for j in subsystems}

Return type:

dict of dicts

data_io.get_reduced_df(df, solvent, solute)[source]

Filter dataframe to keep mobility data for solute in solvent.

Parameters:

  • df (dataframe) – Parameters to compute mobility of solutes in solvents.

  • solvent (str) – Solvent of interest (constituents concatenated to string).

  • solute (str) – Solute of interest.

Raises:

Exception – If several equivalent solvents (ie permutations of the same solvent) are present in the df.

Returns:

res – Reduced dataframe.

Return type:

dataframe

data_io.get_csv_as_string(fpath)[source]

Load csv file content, sanitize and return string.

data_io.sanitize_dataframe(df)[source]

Get rid of empty lines and columns and rebuild if first line was empty

pd.read_excel use first line as header even if it is empty (then columns are named ‘Unnamed N’). Delete empty lines first to make sure the line used as header when rebuilding is not empty. Deleting empty columns is needed to apply str.lower on column names (see get_thermo_from_file()).