Lattices

class tissue_forge.lattice.BondRule(func: Callable[[ParticleHandle, ParticleHandle], BondHandle], part_ids: Tuple[int, int], cell_offset: Tuple[int, int, int])

Simple container for info to create a bond when constructing a lattice

Parameters:

  • func – function of func(p1, p2) that accepts two particle handles and returns a newly created bond.

  • part_ids – pair of particle ids in current current and other unit cell.

  • cell_offset – offset vector of other unit cell relative to current unit cell.

class tissue_forge.lattice.unitcell(N: int, a1: List[float], a2: List[float], a3: List[float], dimensions: int = 3, position: List[List[float]] | None = None, types: List[ParticleType] | None = None, bonds: List[BondRule] | None = None)

A unit cell

A unit cell is a box definition (a1, a2, a3, dimensions), and particle properties for N particles. You do not need to specify all particle properties. Any property omitted will be initialized to defaults. The function create_lattice initializes the system with many copies of a unit cell.

unitcell is a completely generic unit cell representation. See other classes in the lattice module for convenience wrappers for common lattices.

Example:

uc = lattice.unitcell(N=2,
                      a1=[1, 0, 0],
                      a2=[0.2, 1.2, 0],
                      a3=[-0.2, 0, 1.0],
                      dimensions=3,
                      position=[[0, 0, 0], [0.5, 0.5, 0.5]],
                      types=[A, B])
Note:

a1, a2, a3 must define a right handed coordinate system.

Parameters:

  • N (int) – Number of particles in the unit cell.

  • a1 (List[float]) – Lattice vector (3-vector).

  • a2 (List[float]) – Lattice vector (3-vector).

  • a3 (List[float]) – Lattice vector (3-vector).

  • dimensions (int) – Dimensionality of the lattice (2 or 3).

  • position (List[List[float]]) – List of particle positions.

  • types (List[tf.ParticleType]) – List of particle types

  • bonds (List[BondRule]) – bond constructors rules

tissue_forge.lattice.sc(a: float, types: ParticleType | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, True)) → unitcell

Create a unit cell for a simple cubic lattice (3D).

The simple cubic lattice unit cell has one particle:

  • [0, 0, 0]

And the box matrix:

  • [[a, 0, 0] [0, a, 0] [0, 0, a]]

Example:

uc = tissue_forge.lattice.sc(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:

  • a – lattice constant

  • types – particle type

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds in the 1-, 2-, and 3-directions

Returns:

a simple cubic lattice unit cell

tissue_forge.lattice.bcc(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True)) → unitcell

Create a unit cell for a body centered cubic lattice (3D).

The body centered cubic lattice unit cell has two particles:

  • [0, 0, 0]

  • [a/2, a/2, a/2]

And the box matrix:

  • [[a, 0, 0] [0, a, 0] [0, 0, a]]

Example:

uc = tissue_forge.lattice.bcc(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:

  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds - between the corner particles - between the corner and center particles

Returns:

a body centered cubic lattice unit cell

tissue_forge.lattice.fcc(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True)) → unitcell

Create a unit cell for a face centered cubic lattice (3D).

The face centered cubic lattice unit cell has four particles:

  • [0, 0, 0]

  • [0, a/2, a/2]

  • [a/2, 0, a/2]

  • [a/2, a/2, 0]]

And the box matrix:

  • [[a, 0, 0] [0, a, 0] [0, 0, a]]

Example:

uc = tissue_forge.lattice.fcc(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:

  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds - between the corner particles - between the corner and the center particles

Returns:

a face centered cubic lattice unit cell

tissue_forge.lattice.sq(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, False)) → unitcell

Create a unit cell for a square lattice (2D).

The square lattice unit cell has one particle:

  • [0, 0]

And the box matrix:

  • [[a, 0] [0, a]]

Example:

uc = tissue_forge.lattice.sq(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:

  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds along the 1-, 2- and 3-directions

Returns:

a square lattice unit cell

tissue_forge.lattice.hex2d(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, False)) → unitcell

Create a unit cell for a hexagonal lattice (2D).

The hexagonal lattice unit cell has two particles:

  • [0, 0]

  • [0, a*sqrt(3)/2]

And the box matrix:

  • [[a, 0] [0, a*sqrt(3)]]

Example:

uc = tissue_forge.lattice.hex2d(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:

  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds along the 1-, 2- and 3-directions

Returns:

a hexagonal lattice unit cell

tissue_forge.lattice.hcp(a: float, c: float | None = None, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, True)) → unitcell

Create a unit cell for a hexagonal close pack lattice (3D).

The hexagonal close pack lattice unit cell has seven particles:

  • [0, a*sqrt(3)/2, 0]

  • [a/2, 0, 0]

  • [a, a*sqrt(3)/2, 0]

  • [a*3/2, 0, 0]

  • [a/2, a*2/sqrt(3), c/2]

  • [a, a/2/sqrt(3), c/2]

  • [a*3/2, a*2/sqrt(3), c/2]

And the box matrix:

  • [[2*a, 0, 0] [0, a*sqrt(3), 0] [0, 0, c]]

Example:

uc = tissue_forge.lattice.hcp(1.0, 2.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:

  • a – lattice constant

  • c – height of lattice (default a)

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds - between the outer particles - between the inner particles - between the outer and inner particles

Returns:

a hexagonal close pack lattice unit cell

tissue_forge.lattice.create_lattice(uc: unitcell, n: int | List[int], origin: List[float] | None = None) → ndarray

Create a lattice

Takes a unit cell and replicates it the requested number of times in each direction. A generic unitcell may have arbitrary vectors a1, a2, and a3. create_lattice will rotate the unit cell so that a1 points in the x direction and a2 is in the xy plane so that the lattice may be represented as a simulation box. When n is a single value, the lattice is replicated n times in each direction. When n is a list, the lattice is replicated n[i] times in each ``i``th direction.

Examples:

tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.sc(a=1.0), n=[2,4,2])
tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.bcc(a=1.0), n=10)
tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.sq(a=1.2), n=[100,10])
tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.hex2d(a=1.0), n=[100,58])
Parameters:

  • uc – unit cell

  • n – number of unit cells to create along all/each direction(s)

  • origin – origin to begin creating lattice (default centered about simulation origin)

Returns:

particles created in every unit cell