lattice Module

The lattice module define the class to handle 3D crystal lattices (the 14 Bravais lattices).

class pymicro.crystal.lattice.Crystal(lattice, basis=None, basis_labels=None, basis_sizes=None, basis_colors=None)

Bases: object

The Crystal class to create any particular crystal structure.

A crystal instance is composed by:

  • one of the 14 Bravais lattice

  • a point basis (or motif)

__init__(lattice, basis=None, basis_labels=None, basis_sizes=None, basis_colors=None)

Create a Crystal instance with the given lattice and basis.

This create a new instance of a Crystal object. The given lattice is assigned to the crystal. If the basis is not specified, it will be one atom at (0., 0., 0.).

Parameters
  • lattice – the Lattice instance of the crystal.

  • basis (list) – A list of tuples containing the position of the atoms in the motif.

  • basis_labels (list) – A list of strings containing the description of the atoms in the motif.

  • basis_labels – A list of float between 0. and 1. (default 0.1) to sale the atoms in the motif.

  • basis_colors (list) – A list of vtk colors of the atoms in the motif.

class pymicro.crystal.lattice.CrystallinePhase(phase_id=1, name='unknown', lattice=None)

Bases: object

__init__(phase_id=1, name='unknown', lattice=None)

Create a new crystalline phase.

The phase_id attribute is used to identify the phase in data sets where it can be referred to in phase_map for instance.

get_lattice()

Returns the crystal lattice.

set_lattice(lattice)

Set the crystal lattice.

Parameters

lattice (Lattice) – the crystal lattice.

get_symmetry()

Returns the type of Symmetry of the Lattice.

to_dict()
static from_dict(d)
class pymicro.crystal.lattice.Symmetry(value)

Bases: Enum

Class to describe crystal symmetry defined by its Laue class symbol.

cubic = 'm3m'
hexagonal = '6/mmm'
orthorhombic = 'mmm'
tetragonal = '4/mmm'
trigonal = 'bar3m'
monoclinic = '2/m'
triclinic = 'bar1'
static from_string(s)
to_string()
static from_space_group(space_group_number)

Create an instance of the Symmetry class from a TSL symmetry number.

Raises

ValueError – if the space_group_number is not between 1 and 230.

Parameters

space_group_number (int) – the number asociated with the

space group (between 1 and 230). :return: an instance of the Symmetry class

static from_tsl(tsl_number)

Create an instance of the Symmetry class from a TSL symmetry number.

Returns

an instance of the Symmetry class

symmetry_operators(use_miller_bravais=False)

Define the equivalent crystal symmetries.

Those come from Randle & Engler, 2000. For instance in the cubic crystal struture, for instance there are 24 equivalent cube orientations.

Returns array

A numpy array of shape (n, 3, 3) where n is the number of symmetries of the given crystal structure.

move_vector_to_FZ(v)

Move the vector to the Fundamental Zone of a given Symmetry instance.

Parameters

v – a 3 components vector.

Returns

a new 3 components vector in the fundamental zone.

move_rotation_to_FZ(g, verbose=False)

Compute the rotation matrix in the Fundamental Zone of a given Symmetry instance.

Parameters
  • g – a 3x3 matrix representing the rotation.

  • verbose – flag for verbose mode.

Returns

a new 3x3 matrix for the rotation in the fundamental zone.

stiffness_matrix(elastic_constants)

Build the stiffness matrix for this symmetry using Voigt convention.

Parameters

elastic_constants (list) – the elastic constants (the number must correspond to the type of symmetry, eg 3 for cubic).

Return ndarray

a numpy array of shape (6, 6) representing the stiffness matrix.

static orthotropic_constants_from_stiffness(C)

Return orthotropic elastic constants from stiffness matrix.

Parameters

C (ndarray) – a numpy array of shape (6, 6) representing the stiffness matrix.

Return dict OrthoElas

Dict of orthotropic elastic constants corresponding to the input stiffness matrix. Keys are ‘E1’,’E2’,’E3’,’nu12’,’nu13’,’nu23’,’G12’,’G13’,’G23’

class pymicro.crystal.lattice.Lattice(matrix, centering='P', symmetry=None)

Bases: object

The Lattice class to create one of the 14 Bravais lattices.

This particular class has been partly inspired from the pymatgen project at https://github.com/materialsproject/pymatgen

Any of the 7 lattice systems (each corresponding to one point group) can be easily created and manipulated.

The lattice centering can be specified to form any of the 14 Bravais lattices:

  • Primitive (P): lattice points on the cell corners only (default);

  • Body (I): one additional lattice point at the center of the cell;

  • Face (F): one additional lattice point at the center of each of the faces of the cell;

  • Base (A, B or C): one additional lattice point at the center of each of one pair of the cell faces.

a = 0.352 # FCC Nickel
l = Lattice.face_centered_cubic(a)
print(l.volume())

Additionnally the point-basis can be controlled to address non Bravais lattice cells. It is set to a single atoms at (0, 0, 0) by default so that each cell is a Bravais lattice but may be changed to something more complex to achieve HCP structure or Diamond structure for instance.

__init__(matrix, centering='P', symmetry=None)

Create a crystal lattice (unit cell).

Create a lattice from a 3x3 matrix. Each row in the matrix represents one lattice vector. The unit is nm.

Parameters
  • matrix (ndarray) – the 3x3 matrix representing the crystal lattice.

  • centering (str) –

reciprocal_lattice()

Compute the reciprocal lattice.

The reciprocal lattice defines a crystal in terms of vectors that are normal to a plane and whose lengths are the inverse of the interplanar spacing. This method computes the three reciprocal lattice vectors defined by:

\[* a.a^* = 1 * b.b^* = 1 * c.c^* = 1\]
property matrix

Returns a copy of matrix representing the Lattice.

get_symmetry()

Returns the type of Symmetry of the Lattice.

static symmetry(crystal_structure=Symmetry.cubic, use_miller_bravais=False)

Define the equivalent crystal symmetries.

Those come from Randle & Engler, 2000. For instance in the cubic crystal struture, for instance there are 24 equivalent cube orientations.

Parameters

crystal_structure – an instance of the Symmetry class describing the crystal symmetry.

Raises

ValueError – if the given symmetry is not supported.

Returns array

A numpy array of shape (n, 3, 3) where n is the number of symmetries of the given crystal structure.

get_lattice_parameters()

This function create a list of the independent lattice parameters depending on the symmetry.

Returns

a list of the lattice parameters.

guess_symmetry()

Guess the lattice symmetry from the geometry.

static guess_symmetry_from_parameters(a, b, c, alpha, beta, gamma)

Guess the lattice symmetry from the geometrical parameters.

static from_cif(file_path)

Create a crystal Lattice using information contained in a given CIF file (Crystallographic Information Framework, a standard for information interchange in crystallography).

Reference: S. R. Hall, F. H. Allen and I. D. Brown, The crystallographic information file (CIF): a new standard archive file for crystallography, Acta Crystallographica Section A, 47(6):655-685 (1991) doi = 10.1107/S010876739101067X

Note

Lattice constants are given in Angstrom in CIF files and so converted to nanometer.

Parameters

file_path (str) – The path to the CIF file representing the crystal structure.

Returns

A Lattice instance corresponding to the given CIF file.

static from_symbol(symbol)

Create a crystal Lattice using information contained in a unit cell.

Parameters

symbol: The chemical symbol of the crystal (eg ‘Al’)

Returns

A Lattice instance corresponding to the given element.

static cubic(a)

Create a cubic Lattice unit cell.

Parameters

a: first lattice length parameter (a = b = c here)

Returns

A Lattice instance corresponding to a primitice cubic lattice.

static body_centered_cubic(a)

Create a body centered cubic Lattice unit cell.

Parameters

a: first lattice length parameter (a = b = c here)

Returns

A Lattice instance corresponding to a body centered cubic lattice.

static face_centered_cubic(a)

Create a face centered cubic Lattice unit cell.

Parameters

a: first lattice length parameter (a = b = c here)

Returns

A Lattice instance corresponding to a face centered cubic lattice.

static tetragonal(a, c)

Create a tetragonal Lattice unit cell.

Parameters

a: first lattice length parameter

c: third lattice length parameter (b = a here)

Returns

A Lattice instance corresponding to a primitive tetragonal lattice.

static body_centered_tetragonal(a, c)

Create a body centered tetragonal Lattice unit cell.

Parameters

a: first lattice length parameter

c: third lattice length parameter (b = a here)

Returns

A Lattice instance corresponding to a body centered tetragonal lattice.

static orthorhombic(a, b, c)

Create a tetragonal Lattice unit cell with 3 different length parameters a, b and c.

static base_centered_orthorhombic(a, b, c)

Create a based centered orthorombic Lattice unit cell.

Parameters

a: first lattice length parameter

b: second lattice length parameter

c: third lattice length parameter

Returns

A Lattice instance corresponding to a based centered orthorombic lattice.

static body_centered_orthorhombic(a, b, c)

Create a body centered orthorombic Lattice unit cell.

Parameters

a: first lattice length parameter

b: second lattice length parameter

c: third lattice length parameter

Returns

A Lattice instance corresponding to a body centered orthorombic lattice.

static face_centered_orthorhombic(a, b, c)

Create a face centered orthorombic Lattice unit cell.

Parameters

a: first lattice length parameter

b: second lattice length parameter

c: third lattice length parameter

Returns

A Lattice instance corresponding to a face centered orthorombic lattice.

static hexagonal(a, c)

Create a hexagonal Lattice unit cell with length parameters a and c.

static rhombohedral(a, alpha)

Create a rhombohedral Lattice unit cell with one length parameter a and the angle alpha.

static monoclinic(a, b, c, alpha)

Create a monoclinic Lattice unit cell with 3 different length parameters a, b and c. The cell angle is given by alpha. The lattice centering id primitive ie. ‘P’

static base_centered_monoclinic(a, b, c, alpha)

Create a based centered monoclinic Lattice unit cell.

Parameters

a: first lattice length parameter

b: second lattice length parameter

c: third lattice length parameter

alpha: first lattice angle parameter

Returns

A Lattice instance corresponding to a based centered monoclinic lattice.

static triclinic(a, b, c, alpha, beta, gamma)

Create a triclinic Lattice unit cell with 3 different length parameters a, b, c and three different cell angles alpha, beta and gamma.

..note:

This method is here for the sake of completeness since one can
create the triclinic cell directly using the `from_parameters`
method.
static from_symmetry(symmetry, parameters)

Create a new lattice based on a type of symmetry and a list of lattice parameters.

The type of symmetry should be an instance of Symmetry and the list of parameters should contain the appropriate number: 1 for cubic, 2 for hexagonal, tetragonal or trigonal, 3 for orthorhombic, 4 for monoclinic or 6 for triclinic.

Parameters
  • symmetry – an instance of Symmetry.

  • parameters (list) – a list of the lattice parameters.

Returns

the newly created Lattice instance.

static from_parameters(a, b, c, alpha, beta, gamma, x_aligned_with_a=True, centering='P', symmetry=Symmetry.triclinic)

Create a Lattice using unit cell lengths and angles (in degrees). The lattice centering can also be specified (among ‘P’, ‘I’, ‘F’, ‘A’, ‘B’ or ‘C’).

Parameters
  • a (float) – first lattice length parameter.

  • b (float) – second lattice length parameter.

  • c (float) – third lattice length parameter.

  • alpha (float) – first lattice angle parameter.

  • beta (float) – second lattice angle parameter.

  • gamma (float) – third lattice angle parameter.

  • x_aligned_with_a (bool) – flag to control the convention used to define the Cartesian frame.

  • centering (str) – lattice centering (‘P’ by default) passed to the Lattice class.

  • symmetry – a Symmetry instance to be passed to the lattice.

Returns

A Lattice instance with the specified lattice parameters and centering.

volume()

Compute the volume of the unit cell.

get_hkl_family(hkl)

Get a list of the hkl planes composing the given family for this crystal lattice.

Parameters

hkl: miller indices of the requested family

Returns

A list of the hkl planes in the given family.

get_slip_systems(slip_type='oct')

Create a list of the slip systems of a given type for this lattice.

Parameters

slip_type (str) – a string describing the slip system type, should be in (oct, 111, cube, 001, 112, basal, prism)

class pymicro.crystal.lattice.SlipSystem(plane, direction)

Bases: object

A class to represent a crystallographic slip system.

A slip system is composed of a slip plane (most widely spaced planes in the crystal) and a slip direction (highest linear density of atoms in the crystal).

__init__(plane, direction)

Create a new slip system object with the given slip plane and slip direction.

get_slip_plane()
get_slip_direction()
static from_indices(plane_indices, direction_indices, lattice=None)

create a slip system from the indices of the plane and the direction.

This method create a SlipSystem instance by associating a slip plane and a slip direction both given by their Miller indices. In the case of a hexagonal crystal lattice, the Miller-Bravais (4 indices) notation can be used. If this notation is used without specifying any lattice, a default hexagonal lattice is created.

Parameters
  • plane_indices (tuple) – the miller indices for the slip plane.

  • direction_indices (tuple) – the miller indices for the slip direction.

  • lattice (Lattice) – the crystal lattice.

Returns

the new SlipSystem instance.

Raise

ValueError if the 4 indices notation is used with a non hexagonal crystal lattice.

static get_slip_systems(slip_type='oct', lattice=None)

Get all slip systems for a given hkl plane family.

A string is used to describe the slip system type:
  • cube or 001, for [110] slip in (001) planes

  • oct or 111 for [110] slip in (111) planes

  • 112 for [111] slip in (112) planes

  • basal for [11-20] slip in (0001) planes (hexagonal)

  • prism for [11-20] slip in (1-100) planes (hexagonal)

Parameters

slip_type (str) – a string describing the slip system type.

Return list

a list of SlipSystem.

class pymicro.crystal.lattice.HklObject(h, k, l, lattice=None)

Bases: object

An abstract class to represent an object related to a crystal lattice and which can be described by Miller indices.

__init__(h, k, l, lattice=None)

Create a new hkl object with the given Miller indices and crystal lattice.

property lattice
set_lattice(lattice)

Assign a new Lattice to this instance.

Parameters

lattice – the new crystal lattice.

property h
property k
property l
miller_indices()

Returns an immutable tuple of the plane Miller indices.

static skip_higher_order(hkl_list, keep_friedel_pair=False, verbose=False)

Create a copy of a list of some hkl object retaining only the first order.

Parameters
  • hkl_list (list) – The list of HklObject.

  • keep_friedel_pair (bool) – flag to keep order -1 in the list.

  • verbose (bool) – activate verbose mode.

Returns list

A new list of HklObject without any multiple reflection.

class pymicro.crystal.lattice.HklDirection(h, k, l, lattice=None)

Bases: HklObject

direction()

Returns a normalized vector, expressed in the cartesian coordinate system, corresponding to this crystallographic direction.

angle_with_direction(hkl)

Computes the angle between this crystallographic direction and the given direction (in radian).

static angle_between_directions(hkl1, hkl2, lattice=None)

Computes the angle between two crystallographic directions (in radian).

Parameters
  • hkl1 (tuple) – The triplet of the miller indices of the first direction.

  • hkl2 (tuple) – The triplet of the miller indices of the second direction.

  • lattice (Lattice) – The crystal lattice, will default to cubic if not specified.

Returns float

The angle in radian.

static three_to_four_indices(u, v, w)

Convert from Miller indices to Miller-Bravais indices. this is used for hexagonal crystal lattice.

static four_to_three_indices(U, V, T, W)

Convert from Miller-Bravais indices to Miller indices. this is used for hexagonal crystal lattice.

static angle_between_4indices_directions(hkil1, hkil2, ac)

Computes the angle between two crystallographic directions in a hexagonal lattice.

The solution was derived by F. Frank in: On Miller - Bravais indices and four dimensional vectors. Acta Cryst. 18, 862-866 (1965)

Parameters
  • hkil1 (tuple) – The quartet of the indices of the first direction.

  • hkil2 (tuple) – The quartet of the indices of the second direction.

  • ac (tuple) – the lattice parameters of the hexagonal structure in the form (a, c).

Returns float

The angle in radian.

find_planes_in_zone(max_miller=5)

This method finds the hkl planes in zone with the crystallographic direction. If (u,v,w) denotes the zone axis, this means finding all hkl planes which verify \(h.u + k.v + l.w = 0\).

Parameters

max_miller – The maximum miller index to limt the search`

Returns list

A list of HklPlane objects describing all the planes in zone with the direction.

class pymicro.crystal.lattice.HklPlane(h, k, l, lattice=None)

Bases: HklObject

This class define crystallographic planes using Miller indices.

A plane can be create by speficying its Miller indices and the crystal lattice (default is cubic with lattice parameter of 1.0).

a = 0.405 # FCC Aluminium
l = Lattice.cubic(a)
p = HklPlane(1, 1, 1, lattice=l)
print(p)
print(p.scattering_vector())
print(p.interplanar_spacing())

Note

Miller indices are defined in terms of the inverse of the intercept of the plane on the three crystal axes a, b, and c.

normal()

Returns the unit vector normal to the plane.

We use of the repiprocal lattice to compute the normal to the plane and return a normalised vector.

scattering_vector()

Calculate the scattering vector of this HklPlane.

The scattering vector (or reciprocal lattice vector) is normal to this HklPlane and its length is equal to the inverse of the interplanar spacing. In the cartesian coordinate system of the crystal, it is given by:

..math

G_c = h.a^* + k.b^* + l.c^*

Returns

a numpy vector expressed in the cartesian coordinate system of the crystal.

friedel_pair()

Create the Friedel pair of the HklPlane.

interplanar_spacing()

Compute the interplanar spacing. For cubic lattice, it is:

\[d = a / \sqrt{h^2 + k^2 + l^2}\]

The general formula comes from ‘Introduction to Crystallography’ p. 68 by Donald E. Sands.

bragg_angle(lambda_keV, verbose=False)

Compute the Bragg angle for this HklPlane at the given energy.

Note

For this calculation to work properly, the lattice spacing needs to be in nm units.

static four_to_three_indices(U, V, T, W)

Convert four to three index representation of a slip plane (used for hexagonal crystal lattice).

static three_to_four_indices(u, v, w)

Convert three to four index representation of a slip plane (used for hexagonal crystal lattice).

is_in_list(hkl_planes, friedel_pair=False)

Check if the hkl plane is in the given list.

By default this relies on the built in in test from the list type which in turn calls in the __eq__ method. This means it will return True if a plane with the exact same miller indices (and same lattice) is in the list. Turning on the friedel_pair flag will allow to test also the Friedel pair (-h, -k, -l) and return True if it is in the list. For instance (0,0,1) and (0,0,-1) are in general considered as the same lattice plane.

static is_same_family(hkl1, hkl2, crystal_structure=Symmetry.cubic)

Static mtd to test if both lattice planes belongs to same family.

A family {hkl} is composed by all planes that are equivalent to (hkl) using the symmetry of the lattice. The lattice assoiated with hkl2 is not taken into account here.

static get_family(hkl, lattice=None, include_friedel_pairs=False, crystal_structure=Symmetry.cubic)

Static method to obtain a list of the different crystallographic planes in a particular family.

Parameters
  • hkl (str) – a sequence of 3 (4 for hexagonal) numbers corresponding to the miller indices.

  • lattice (Lattice) – The reference crystal lattice (default None).

  • include_friedel_pairs (bool) – Flag to include the Friedel pairs in the list (False by default).

  • crystal_structure (str) – A string descibing the crystal structure (cubic by default).

Raises

ValueError – if the given string does not correspond to a supported family.

Returns list

a list of the HklPlane in the given hkl family.

Note

The method account for the lattice symmetry to create a list of equivalent lattice plane from the point of view of the point group symmetry. A flag can be used to include or not the Friedel pairs. If not, the family is contstructed using the miller indices limited the number of minus signs. For instance (1,0,0) will be in the list and not (-1,0,0).

multiplicity(symmetry=Symmetry.cubic)

compute the general multiplicity for this HklPlane and the given Symmetry.

Parameters

symmetry (Symmetry) – The crystal symmetry to take into account.

Returns

the number of equivalent planes in the family.

slip_trace(orientation, n_int=<Mock name='mock.array()' id='140580350136272'>, view_up=<Mock name='mock.array()' id='140580350136272'>, trace_size=100, verbose=False)

Compute the intersection of the lattice plane with a particular plane defined by its normal.

Parameters
  • orientation – The crystal orientation.

  • n_int – normal to the plane of intersection (laboratory local frame).

  • view_up – vector to place upwards on the plot.

  • trace_size (int) – size of the trace.

  • verbose – activate verbose mode.

Returns

a numpy array with the coordinates of the two points defining the trace.

static plot_slip_traces(orientation, hkl='111', n_int=<Mock name='mock.array()' id='140580350136272'>, view_up=<Mock name='mock.array()' id='140580350136272'>, verbose=False, title=True, legend=True, trans=False, str_plane=None)

A method to plot the slip planes intersection with a particular plane (known as slip traces if the plane correspond to the surface). A few parameters can be used to control the plot looking. Thank to Jia Li for starting this code.

Parameters
  • orientation – The crystal orientation.

  • hkl – a string representing the slip plane family (eg. 111 or 110)

or the list of HklPlane instances. :param n_int: normal to the plane of intersection. :param view_up: vector to place upwards on the plot. :param verbose: activate verbose mode. :param title: display a title above the plot. :param legend: display the legend. :param trans: use a transparent background for the figure (useful to overlay the figure on top of another image). :param str_plane: particular string to use to represent the plane in the image name.

static plot_XY_slip_traces(orientation, hkl='111', title=True, legend=True, trans=False, verbose=False)

Helper method to plot the slip traces on the XY plane.

static plot_YZ_slip_traces(orientation, hkl='111', title=True, legend=True, trans=False, verbose=False)

Helper method to plot the slip traces on the YZ plane.

static plot_XZ_slip_traces(orientation, hkl='111', title=True, legend=True, trans=False, verbose=False)

Helper method to plot the slip traces on the XZ plane.

static indices_from_two_directions(uvw1, uvw2)

Two crystallographic directions \(uvw_1\) and \(uvw_2\) define a unique set of hkl planes. This does not depends on the crystal symmetry.

\[\begin{split}h = v_1 . w_2 - w_1 . v_2 \\ k = w_1 . u_2 - u_1 . w_2 \\ l = u_1 . v_2 - v_1 . u_2\end{split}\]
Parameters
  • uvw1 – The first instance of the HklDirection class.

  • uvw2 – The second instance of the HklDirection class.

Return h, k, l

the miller indices of the HklPlane defined by the two directions.