Models and Queries

These modules define the data models for imeall.gb_models.GrainBoundary and imeall.gb_models.SubGrainBoundary structures and the SQL and directory tree database. They also contains classes for performing maintenance of the grain boundary database and querying and copying structures from the directory tree.

Maintenance

imeall.models.GBMaintenance contains methods for performing maintenance and query operations on the directory tree structure and modifying gb.json and subgb.json files.

class imeall.models.GBMaintenance

Collection of maintenance routines for the GB database. Methods include routines to regenerate all the csl lattices in the database, take a new grain boundary profile picture for multiple directories, update the gb.json information if a new grain boundary property is desired.

add_key_to_dict(dirname, new_key, new_value, dict_type='subgb.json', modify=False)

Add single key to .json dictionary.

Parameters:

• dirname (str) – directory name with json dictionary.
• new_key (str) – key to add to dictionary.
• new_value (generic) – value to add to dictionary.
• dict_type (str, optional) – Type of json dict ‘subgb.json’ or ‘gb.json’.
• modify (bool) – If True json file will be overwritten.

Returns:

Updated json dictionary.

Return type:

dict

fix_json(path)

If json file is corrupted and contains two {}{} dictionaries, this function selects the second of the two dictionaries and overwrites json file.

Parameters:path (str) – path to corrupted dictionary.

remove_eo_files(path, num_deleted_files, dryrun=False)

Remove files with pattern matching jobname.[eo][0-9]+.

Parameters:

• path (str) – root path to start walking downwards from.
• num_deleted_files (int) – Number of job files deleted.
• dryrun (bool) – (Default: True).

Returns:

Number of deleted files.

retake_pic(fname, translate=False, toggle=False, confirm=True)

DEPRECATED If using AtomEye take grain boundary profile pic in directory requires gb directory with gbid.xyz file in it. Set confirm=False to not prompt for overwrite. In future versions OVITO will be default image generator.

update_json(json_path, new_keys=[], new_values=[], dryrun=True)

Update or add multiple keys to json dictionaries.

Parameters:

• json_path (str) – directory name where gb.json file needs to be updated.
• new_keys (list) – list of new keys.
• new_values (list) – list of new values
• dryrun (bool) – If False json file is over written with new keys.

Returns:

Updated json dictionary.

Return type:

dict

Queries

imeall.models.GBQuery contains methods for checking out and copying structure files and json dictionaries from the directory tree grain boundary database.

class imeall.models.GBQuery

Routines for grabbing desired .xyz files and paths.

copy_gb_dirtree(material='alphaFe', or_axis='0,0,1', pots=['PotBH.xml'], target_dir='./', gb_type='tilt')

Pull all minimum energy structures, using pull_minen_structs(), from database for an orientation axis and copy them to target_dir. Useful for checking out structures into a unique directory for specialized analysis.

Parameters:

• material (str) – material name
• or_axis (str) – csv serialized vector of orientation axis
• pots – list of potential parameter files.
• target_dir – Location to copy files to (Default: ‘./’).
• gb_type (str) – Options ‘tilt’ or ‘twist’.

Todo

• Add kwargs to pull_minen_structs to provide additional selection criteria.

pull_minen_structs(material='alphaFe', or_axis='1,1,1', pots=['PotBH.xml'], gb_type='tilt')

Grab the minimum energy structure json dictionaries for a given material, orientation_axis, and potential(s) parameter filenames.

Parameters:

• material (str,optional) – Material to investigate.
• or_axis (str,optional) – Orientation axis “1,1,1”.
• pots (list) – list of potentials parameter files.
• gb_type (str) – Options ‘tilt’ or ‘twist’.

Returns:

List of SubGrainBoundary Model represented as dictionaries.

Return type:

list[SubGrainBoundary]

SQL Models

These classes define the data models for the imeall.gb_models.GrainBoundary and imeall.gb_models.SubGrainBoundary models.

class imeall.gb_models.GrainBoundary(*args, **kwargs)

GrainBoundary is a peewee :peewee:`Model` of the canonical parent grain. Model is connected to the SQL database of the grain boundaries. All vectors are serialized to csv string for storage.

orientation_axis

str – orientation axis defining the grain.

angle

str – misorientation angle for defining the grain.

boundary_plane

str – boundary plane normal defining the grain.

path

str – Full directory string relative to the grain boundary database root.

gb_type

str – Grain boundary type (tilt, twist, general).

z_planes

list – Location of center of interfacial planes.

n_at

int – Number of grains in parent.

class imeall.gb_models.SubGrainBoundary(*args, **kwargs)

SubGrainBoundary Model.

path

str – relative to the GRAIN_BOUNDARY database root (set in the application instance/config.py file).

canonical_grain(

class:GrainBoundary): Each SubGrainBoundary has a parent GrainBoundary model.

rbt

str – rigid body translations.

potential

str – Potential parameter file.

rcut

float – atom deletion criterion.

area

float – grain boundary interfacial area.

n_at

int – number of atoms in subgrain structure.

E_gb

float – grain boundary energies.

E_gb_init

float – Energy of initial unrelaxed structure.

notes

str – Special notes of interest about this boundary.

gbid

str – SubGrainBoundary id.

class imeall.gb_models.Fracture(*args, **kwargs)

Fracture data Model.

fracture_system

str – Serialized string in form [crack direction](crack plane).

G

float – stress energy release rate.

strain_rate

float – time incremental rate of strain increase fs^{-1}

sim_T

float – simulation temperature.

Serialization Methods

These methods flip vector or list data back and forth between comma separated value strings which can be stored in the SQL database.

This module contains key grain boundary data models for the SQL database. Also operates as a command line tool to populate local versions of the database.

imeall.gb_models.create_tables(database)

Create GrainBoundary, and SubGrainBoundary Tables.

Parameters:database( – py:class:SqliteDatabase)

SQL Database Methods

Methods for updating and checking the integrity of the SQL database. These methods ensure the directory tree and the SQL database remain normalized and synchronized.

This module contains key grain boundary data models for the SQL database. Also operates as a command line tool to populate local versions of the database.

imeall.gb_models.add_conv_key(material='alphaFe', or_axis='001')

Check if subgb.json dictionary contains a convergence key. If not add key to subgb.json file and default to false.

Parameters:

• material (str) – name of material to search.
• or_axis (str) – orientation axis.

imeall.gb_models.gb_check_dir_integrity(material='alphaFe', or_axis='001')

Check if directory in directory tree contains a grain boundary json file, and update sql database to include the parent grain if it is missing.

imeall.gb_models.gb_check_path(material='alphaFe', or_axis='001', modify_db=False)

Compare consistency between location of subgb.json paths and the paths in the closure tree. If path is missing from directory tree delete from the SQL database.

Parameters:

• material (str) – material.
• or_axis (str) – orientation axis.
• modify_db (bool) – If True database will be updated.

imeall.gb_models.gb_check_conv(material='alphaFe', or_axis='001', modify_db=False)

Scans through grainboundary directory tree, inspecting the subgrain dictionary and the SubGrainBoundary to test if the grain boundary energy, number of atoms, gb_area, and convergence flag are consistent. If modify_db is True the SQLite model will be updated.

Parameters:

• material – Which material to do check json/database convergence consistency on.
• or_axis – Which orientation axis to check.
• modify_db – Boolean. If True updates gb_model in database otherwise just prints inconsistent grain json/database value.

imeall.gb_models.gb_check_force(material='alphaFe', or_axis='001', force_tol=0.05, modify_db=False, gb_start=0, sub_start=0)

Recurse through directory tree, loading the structure file, json dict and the model for each subgrain. Check that the force tolerance in the structure file has actually been met for convergence.

Parameters:

• material (str) – material string.
• or_axis (str) – orientation axis.
• force_tol (float) – Max force magnitude on the relaxed structures.
• modify_db (bool) – If True SubGrainBoundary will be updated.
• gb_start (int) – Start from this grain boundary in list.
• sub_start (int) – Start from this subgrainboundary in list.

imeall.gb_models.change_json_key(material='alphaFe', or_axis='001')

Replace ‘_traj’ string in subgb_dict[‘gbid’] method. Can be modified to update or correct database/subgb strings in json files.

Parameters:

• material (str) – material to select.
• or_axis (str) – orientation axis to select.

imeall.gb_models.populate_db(material='alphaFe', or_axis='001', gbid='', modify=False)

Add canonical grains to SQLite database, and all SubGrainBoundaries that can be found below it in the directory tree from their subgb.json files.

Parameters:

• material (str) – material.
• or_axis (str) – orientation axis.
• gbid (str, optional) – To add a specific canonical grain from its id.
• modify (bool) – If True database will be updated.