Creating dislocations

Quick guide: See the example Creating a dislocation in a slab.

There are three functions for creating dislocations in a material: Dislocation, ScrewDislocation and EdgeDislocation for setting up a general dislocation, a screw dislocation and an edge dislocation. It is perfectly allright to use the general Dislocation function to set up and edge or screw dislocation.

asap3.setup.dislocation.Dislocation(origin, line, Burgers, PoissonRatio=None, debug=None)[source]

Set up a dislocation with mixed screw and edge character.

Sets up a straight dislocation through a specified point with a given Burgers vector. The displacement field is constructed as the sum of the fields of the edge and screw components, except if one of the components is zero, in which case it is omitted.

In the following, a 3-vector may be a tuple, list or NumPy array with three elements.

Parameters:

  • origin (array_like) – A point on the dislocation line, as a 3-vector.

  • line (array_like) – The dislocation line, as a 3-vector. Only the direction matters.

  • Burgers (array_like) – The Burgers vector of the dislocation, as a 3-vector.

  • PoissonRatio (float, optional) – Poisson’s ratio of the material. The default is 1/3.

  • debug (bool, optional) – Print debugging information while evaluating the field.

Returns:

asap3.setup.displacementfield.DisplacementField – The displacement field of the dislocation. Displacement fields may be added together and multiplied by scalars. The field can be applied to any Atoms object using field.apply_to(atoms); the atoms are modified using the get_positions and set_positions methods.

Examples

>>> from asap3 import *
>>> from ase.lattice.cubic import FaceCenteredCubic
>>> from asap3.setup.dislocation import Dislocation
>>> splitting = 5
>>> size = (30, 25, 7)
>>> Gold = "Au"
>>> slab = FaceCenteredCubic(directions=((1,1,-2), (-1,1,0), (1,1,1)),
...                          size=size, symbol=Gold, pbc=False)
>>> basis = slab.get_cell()
>>> # Center of system, slight offset so as not to hit an atom.
>>> center = (0.5 * array([basis[0,0], basis[1,1], basis[2,2]])
...           + array([0.1, 0.1, 0.1]))
>>> offset = 0.5 * splitting * slab.miller_to_direction((-1,0,1))
>>> d1 = Dislocation(center - offset, slab.miller_to_direction((-1,-1,0)),
...                  slab.miller_to_direction((-2,-1,1))/6.0)
>>> d2 = Dislocation(center + offset, slab.miller_to_direction((1,1,0)),
...                  slab.miller_to_direction((1,2,1))/6.0)
>>> atoms = Atoms(slab)
>>> (d1+d2).apply_to(atoms)
asap3.setup.dislocation.ScrewDislocation(origin, line, b, cut=None, debug=None)[source]

Set up a straight screw dislocation.

Sets up a straight screw dislocation through a specified point with a given Burgers vector.

Parameters:

  • origin (array_like) – A point on the dislocation line, as a 3-vector.

  • line (array_like) – The dislocation line, as a 3-vector. Only the direction matters.

  • b (float) – The length of the Burgers vector. A positive value means parallel to the dislocation line, a negative value antiparallel.

  • cut (array_like, optional) – A direction that lies in the cutting plane when starting at the origin, as a 3-vector. If not given, (1.0, 0.0, 0.0) is used, unless that is parallel to the dislocation line, in which case (0.0, 1.0, 0.0) is used.

  • debug (bool, optional) – Print debugging information while evaluating the field.

Returns:

asap3.setup.displacementfield.DisplacementField – The displacement field of the dislocation. Displacement fields may be added together and multiplied by scalars. The field can be applied to any Atoms object using field.apply_to(atoms).

Raises:

TypeError – If b is not a number.

asap3.setup.dislocation.EdgeDislocation(origin, line, Burgers, PoissonRatio=None, debug=None)[source]

Set up a straight edge dislocation.

Sets up a straight edge dislocation through a specified point with a given Burgers vector.

Parameters:

  • origin (array_like) – A point on the dislocation line, as a 3-vector.

  • line (array_like) – The dislocation line, as a 3-vector. Only the direction matters.

  • Burgers (array_like) – The Burgers vector of the dislocation, as a 3-vector. It must be perpendicular to line.

  • PoissonRatio (float, optional) – Poisson’s ratio of the material. Unlike for a screw dislocation, this number is needed in order to calculate the displacement field. The default is 1/3.

  • debug (bool, optional) – Print debugging information while evaluating the field.

Returns:

asap3.setup.displacementfield.DisplacementField – The displacement field of the dislocation. Displacement fields may be added together and multiplied by scalars. The field can be applied to any Atoms object using field.apply_to(atoms).

The DisplacementField object implements a vector function of position. DisplacementField can be added, subtracted, multiplied and divided as expected. In addition, it has a single method for applying the field to an atomic-scale system:

class asap3.setup.displacementfield.DisplacementField(expr)[source]

A displacement field.

Displacement fields are returned e.g. by the setup.dislocation module. They are vector fields and can be applied to a lattice using the apply_to method. They can be added and multiplied by a scalar. A DisplacementField instance can also be used as a function taking an N x 3 array of positions and returning an N x 3 array of displacements.

To create a displacement field, define a function taking an N x 3 array of positions and returning an N x 3 array of displacements, then create the DisplacementField with the function as the sole argument. A lambda construct will often be useful. For an example, see the source code of asap3.setup.dislocation.ScrewDislocation().

apply_to(atoms, fixedbox=0, usepositions=None)[source]

Apply the displacement field to an Atoms object.

The atoms are modified to reflect the displacement field.

Parameters:

  • atoms (ase.Atoms) – The atoms to be displaced.

  • fixedbox (bool, optional) – Adjust the displacement field to keep the corners of the computational box fixed, by adding a smooth displacement field to the specified field. The default is False.

  • usepositions (numpy.ndarray, optional) – An array containing the positions of all atoms, to be used instead of the positions extracted from the atoms. This can be useful if several displacement fields are to be applied to the same system: by giving the original positions as this argument, the fields can be applied sequentially while obtaining an effect similar to adding the fields and then applying the sum. This is mainly useful if the displacement field contains discontinuities, where a previously applied field (or dynamics) may cause some atoms to cross the discontinuity.

Raises:

ValueError – If usepositions has the wrong shape.