# Spin Bath

## BathArray

Documentation for the pycce.BathArray - central class, containing properties of the bath spins.

class BathArray(shape=None, array=None, names=None, hyperfines=None, quadrupoles=None, types=None, imap=None, ca=None, sn=None, hf=None, q=None, efg=None, state=None, center=1)

Subclass of ndarray containing information about the bath spins.

The subclass has fixed structured datatype:

_dtype_bath = np.dtype([('N', np.unicode_, 16),
('xyz', np.float64, (3,)),
('A', np.float64, (3, 3)),
('Q', np.float64, (3, 3))])


Accessing different fields results in the ndarray view.

Each of the fields can be accessed as the attribute of the BathArray instance and modified accordingly. In addition to the name fields, the information of the bath spin types is stored in the types attribute. All of the items in types can be accessed as attributes of the BathArray itself.

Examples

Generate empty BathArray instance.

>>> ba = BathArray((3,))
>>> print(ba)
[('', [0., 0., 0.], [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]], [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]])
('', [0., 0., 0.], [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]], [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]])
('', [0., 0., 0.], [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]], [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]])]


Generate BathArray from the set of arrays:

>>> import numpy as np
>>> ca = np.random.random((2, 3))
>>> sn = ['1H', '2H']
>>> hf = np.random.random((2, 3, 3))
>>> ba = BathArray(ca=ca, hf=hf, sn=sn)
>>> print(ba.N, ba.types)
['1H' '2H'] SpinDict(1H: (1H, 0.5, 26.7519), 2H: (2H, 1, 4.1066, 0.00286))


Warning

Due to how structured arrays work, if one uses a boolean array to access an subarray, and then access the name field, the initial array will not change.

Example:

>>> ha = BathArray((10,), sn='1H')
>>> print(ha.N)
['1H' '1H' '1H' '1H' '1H' '1H' '1H' '1H' '1H' '1H']
>>> bool_mask = np.arange(10) % 2 == 0
>>> print(ha.N)
['1H' '1H' '1H' '1H' '1H' '1H' '1H' '1H' '1H' '1H']


To achieve the desired result, one should first access the name field and only then apply the boolean mask:

>>> ha['N'][bool_mask] = 'e'
>>> print(ha.N)
['e' '1H' 'e' '1H' 'e' '1H' 'e' '1H' 'e' '1H']


Each bath spin can initiallized in some specific state accessing the .state attribute. It takes both state vectors and density matrices as values. See .state attribute documentation for details.

Parameters
• shape (tuple) – Shape of the array.

• array (array-like) – Either an unstructured array with shape (n, 3) containing coordinates of bath spins as rows OR structured ndarray with the same fields as the datatype of the bath.

• name (array-like) – Array of the bath spin name.

• hyperfines (array-like) – Array of the hyperfine tensors with shape (n, 3, 3).

• quadrupoles (array-like) – Array of the quadrupole tensors with shape (n, 3, 3).

• efg (array-like) – Array of the electric field gradients with shape (n, 3, 3) for each bath spin. Used to compute Quadrupole tensors for spins >= 1. Requires the spin types either be found in common_isotopes or specified with types argument.

• types (SpinDict) – SpinDict or input to create one. Contains either SpinTypes of the bath spins or tuples which will initialize those. See pycce.bath.SpinDict documentation for details.

• imap (InteractionMap) – Instance of InteractionMap containing user defined interaction tensors between bath spins stored in the array.

• ca (array-like) – Shorthand notation for array argument.

• sn (array-like) – Shorthand notation for name argument.

• hf (array-like) – Shorthand notation for hyperfines argument.

• q (array-like) – Shorthand notation for quadrupoles argument.

sort(axis=- 1, kind=None, order=None)

Sort array in-place. Is implemented only when imap is None. Otherwise use np.sort.

property h

Dictionary with additional spin Hamiltonian parameters. Key denotes the product of spin operators as:

Either a string containing x, y, z, +, - where each symbol is a corresponding spin operator:

• x == $$S_x$$

• y == $$S_y$$

• z == $$S_z$$

• p == $$S_+$$

• m == $$S_-$$

Several symbols is a product of those spin operators.

Or a tuple with indexes (k, q) for Stevens operators (see https://www.easyspin.org/documentation/stevensoperators.html).

The item is the coupling parameter in float.

Examples

• d['pm'] = 2000 corresponds to the Hamiltonian term $$\hat H_{add} = A \hat S_+ \hat S_-$$ with $$A = 2$$ MHz.

• d[2, 0] = 1.5e6 corresponds to Stevens operator $$B^q_k \hat O^q_k = 3 \hat S_z - s(s+1) \hat I$$ with $$k = 2$$, $$q = 0$$, and $$B^q_k = 1.5$$ GHz.

Type

dict

property name

Array of the name attribute for each spin in the array from types dictionary.

Note

While the value of this attribute should be the same as the N field of the BathArray instance, .name should not be used for production as it creates a new array from types dictionary.

Type

ndarray

property s

Array of the spin (spin value) attribute for each spin in the array from types dictionary.

Type

ndarray

property dim

Array of the dim (dimensions of the spin) attribute for each spin in the array from types dictionary.

Type

ndarray

property gyro

Array of the gyro (gyromagnetic ratio) attribute for each spin in the array from types dictionary.

Type

ndarray

property q

Array of the q (quadrupole moment) attribute for each spin in the array from types dictionary.

Type

ndarray

property detuning

Array of the detuning attribute for each spin in the array from types dictionary.

Type

ndarray

property x

Array of x coordinates for each spin in the array (bath['xyz'][:, 0]).

Type

ndarray

property y

Array of y coordinates for each spin in the array (bath['xyz'][:, 1]).

Type

ndarray

property z

Array of z coordinates for each spin in the array (bath['xyz'][:, 2]).

Type

ndarray

property N

Array of name for each spin in the array (bath['N']).

Type

ndarray

property xyz

Array of coordinates for each spin in the array (bath['xyz']).

Type

ndarray

property A

Array of hyperfine tensors for each spin in the array (bath['A']).

Type

ndarray

property Q

Array of quadrupole tensors for each spin in the array (bath['Q']).

Type

ndarray

property nc

Number of central spins.

Type

int

property state

Array of the bath spin states.

Can have three types of entries:

• None. If entry is None, assumes fully random density matrix. Default value.

• ndarray with shape (s,). If entry is vector, corresponds to the pure state of the spin.

• ndarray with shape (s, s). If entry is a matrix, corresponds to the density matrix of the spin.

Examples

>>> print(ba.state)
[None None]
>>> ba[0].state = np.array([0, 1])
>>> print(ba.state)
[array([0, 1]) None]

Type

BathState

property proj

Array of $$S_z$$ projections of the bath spin states.

Type

ndarray

property has_state

Bool array. True if given spin was initialized with a state, False otherwise.

Type

ndarray

Add spin type to the types dictionary.

Parameters
• *args – Any number of positional inputs to create SpinDict entries. E.g. the tuples of form (name str, spin float, gyro float, q float).

• **kwargs – Any number of keyword inputs to create SpinDict entries. E.g. name = (spin, gyro, q).

For details and allowed inputs see SpinDict documentation.

Returns

A view of self.types instance.

Return type

SpinDict

Add interactions tensor between bath spins with indexes i and j.

Note

If called from the subarray this method does not change the tensors of the total BathArray.

Parameters
• i (int or ndarray (n,)) – Index of the first spin in the pair or array of the indexes of the first spins in n pairs.

• j (int or ndarray with shape (n,)) – Index of the second spin in the pair or array of the indexes of the second spins in n pairs.

• tensor (ndarray with shape (3,3) or (n, 3,3)) – Interaction tensor between the spins i and j or array of tensors.

update(ext_bath, error_range=0.2, ignore_isotopes=True, inplace=True)

Update the properties of the spins in the array using data from other BathArray instance. For each spin in ext_bath check whether there is such spin in the array that has the same position within allowed error range given by error_range and has the same name. If such spins is found in the array, then it’s coordinates, hyperfine tensor and quadrupole tensor are updated using the values of the spin in the ext_bath object.

If ignore_isotopes is true, then the name check ignores numbers in the name of the spins.

Parameters
• ext_bath (BathArray) – Array of the new spins.

• error_range (float) – +- distance in Angstrom within which two positions are considered to be the same. Default is 0.2 A.

• ignore_isotopes (bool) – True if ignore numbers in the name of the spins. Default True.

• inplace (bool) – True if changes parameters of the array in place. If False, returns copy of the array.

Returns

updated BathArray instance.

Return type

BathArray

from_center(center, inplace=True, cube=None, which=0, **kwarg)

Generate hyperfine couplings using either the point dipole approximation or spin density in the .cube format, with the information from the CenterArray instance.

Parameters
• center (CenterArray) – Array, containing properties of the central spin

• inplace (bool) – True if changes parameters of the array in place. If False, returns copy of the array.

• cube (Cube or iterable of Cubes) – An instance of Cube object, which contains spatial distribution of spin density of central spins. For details see documentation of Cube class.

• which (int) – If cube is a single Cube instance, this is an index of the central spin it corresponds to.

• **kwarg – Additional arguments for .from_cube method.

Returns

Updated BathArray instance.

Return type

BathArray

from_point_dipole(position, gyro_center=- 17608.59705, inplace=True)

Generate hyperfine couplings, assuming that bath spins interaction with central spin is the same as the one between two magnetic point dipoles.

Parameters
• position (ndarray with shape (3,)) – position of the central spin

• gyro_center (float or ndarray with shape (3,3)) –

gyromagnetic ratio of the central spin

OR

tensor corresponding to interaction between magnetic field and central spin.

• inplace (bool) – True if changes parameters of the array in place. If False, returns copy of the array.

Returns

Updated BathArray instance with changed hyperfine couplings.

Return type

BathArray

from_cube(cube, gyro_center=- 17608.59705, inplace=True, which=0, **kwargs)

Generate hyperfine couplings, assuming that bath spins interaction with central spin can be approximated as a point dipole, interacting with given spin density distribution.

Parameters
• cube (Cube) – An instance of Cube object, which contains spatial distribution of spin density. For details see documentation of Cube class.

• gyro_center (float) – Gyromagnetic ratio of the central spin.

• inplace (bool) – True if changes parameters of the array in place. If False, returns copy of the array.

Returns

Updated BathArray instance with changed hyperfine couplings.

Return type

BathArray

from_func(func, *args, inplace=True, **kwargs)

Generate hyperfine couplings from user-defined function.

Parameters
• func (func) –

Callable with signature:

func(array, *args, **kwargs)


where array is array of the bath spins,

• *args – Positional arguments of the func.

• **kwargs – Keyword arguments of the func.

• inplace (bool) – True if changes parameters of the array in place. If False, returns copy of the array.

Returns

Updated BathArray instance with changed hyperfine couplings.

Return type

BathArray

from_efg(efg, inplace=True)

Generate quadrupole splittings from electric field gradient tensors for spins >= 1.

Parameters
• efg (array-like) – Array of the electric field gradients for each bath spin. The data for spins-1/2 should be included but can be any value.

• inplace (bool) – True if changes parameters of the array in place. If False, returns copy of the array.

Returns

Updated BathArray instance with changed quadrupole tensors.

Return type

BathArray

dist(position=None)

Compute the distance of the bath spins from the given position.

Parameters

position (ndarray with shape (3,)) – Cartesian coordinates of the position from which to compute the distance. Default is (0, 0, 0).

Returns

Array of distances of each bath spin from the given position in angstrom.

Return type

ndarray with shape (n,)

savetxt(filename, fmt='%18.8f', strip_isotopes=False, **kwargs)

Save name of the isotopes and their coordinates to the txt file of xyz format.

Parameters
• filename (str or file) – Filename or file handle.

• fmt (str) – Format of the coordinate entry.

• strip_isotopes (bool) – True if remove numbers from the name of bath spins. Default False.

• **kwargs – Additional keywords of the numpy.savetxt function.

sort(a, axis=- 1, kind=None, order=None)

Return a sorted copy of an array. Overrides numpy.sort function.

argsort(a, *args, **kwargs)

Return a indexes of an sorted array. Overrides numpy.argsort function.

check_gyro(gyro)

Check if gyro is matrix or scalar.

Parameters

gyro (ndarray or float) – Gyromagnetic ratio matrix or float.

Returns

tuple containing:

• ndarray or float: Gyromagnetic ratio.

• bool: True if gyro is float, False otherwise.

Return type

tuple

point_dipole(pos, gyro_array, gyro_center)

Generate an array hyperfine couplings, assuming point dipole approximation.

Parameters
• pos (ndarray with shape (n, 3)) – Relative position of the bath spins.

• gyro_array (ndarray with shape (n,)) – Array of the gyromagnetic ratios of the bath spins.

• gyro_center (float or ndarray with shape (3, 3)) –

gyromagnetic ratio of the central spin

OR

tensor corresponding to interaction between magnetic field and central spin.

Returns

Array of hyperfine tensors.

Return type

ndarray with shape (n, 3, 3)

same_bath_indexes(barray_1, barray_2, error_range=0.2, ignore_isotopes=True)

Find indexes of the same array elements in two BathArray instances.

Parameters
• barray_1 (BathArray) – First array.

• barray_2 (BathArray) – Second array.

• error_range (float) – If distance between positions in two arrays is smaller than error_range they are assumed to be the same.

• ignore_isotopes (bool) – True if ignore numbers in the name of the spins. Default True.

Returns

tuple containing:

• ndarray: Indexes of the elements in the first array found in the second.

• ndarray: Indexes of the elements in the second array found in the first.

Return type

tuple

Using mpi4py broadcast BathArray or CenterArray to all processes. :param array: Array to broadcast. :type array: BathArray or CenterArray :param root: Rank of the process to broadcast from. :type root: int

Returns

Return type
utilities.rotmatrix(final_vector)

Generate 3D rotation matrix which applied on initial vector will produce vector, aligned with final vector.

Examples

>>> R = rotmatrix([0,0,1], [1,1,1])
>>> R @ np.array([0,0,1])
array([0.577, 0.577, 0.577])

Parameters
• initial_vector (ndarray with shape(3, )) – Initial vector.

• final_vector (ndarray with shape (3, )) – Final vector.

Returns

Rotation matrix.

Return type

ndarray with shape (3, 3)

### BathState

class BathState(size)

Class for storing the state of the bath spins. Usually is not generated directly, but accessed as an BathArray.state attribute.

Parameters

size (int) – Number of bath states to be stored.

gen_pure(rho, dim)

Generate pure states from the $$S_z$$ projections to be stored in the given BathState object.

Parameters
• rho (ndarray with shape (n, )) – Array of the desired projections.

• dim (ndarray with shape (n,)) – Array of the dimensions of the spins.

Returns

View of the BathState object.

Return type

BathState

property state

Return an underlying object array.

Type

ndarray

property pure

Bool property. True if given entry is a pure state, False otherwise.

Type

ndarray

property proj

Projections of bath states on $$S_z$$.

Type

ndarray

property has_state

Bool property. True if given element was initialized as a state, False otherwise.

Type

ndarray

project(rotation=None)

Generate projections of bath states on $$S_z$$.

Parameters

rotation (optional, ndarray with shape (3, 3)) – Matrix used to transform $$S_z$$ matrix as $$S_z' = R^{\dagger} S_z R$$.

Returns

Array with projections of the state.

Return type

ndarray with shape (n, )

property shape

Shape of the BathState underlying array.

Type

tuple

property size

Size of the BathState underlying array.

Type

int

any(*args, **kawrgs)

Returns the output of .has_state.any method. :param *args: Positional arguments of .has_state.any method. :param **kawrgs: Keyword arguments of .has_state.any method.

Returns

True if any entry is initialized. Otherwise False.

Return type

bool

### Cube

class Cube(filename)

Class to process the .cube datafiles with spin polarization.

Parameters

filename (str) – Name of the .cube file.

First two lines of the .cube file.

Type

str

origin

Coordinates of the origin in angstrom.

Type

ndarray with shape (3,)

voxel

Parameters of the voxel - unit of the 3D grid in angstrom.

Type

ndarray with shape (3,3)

size

Size of the cube.

Type

ndarray with shape (3,)

atoms

Array of atoms in the cube.

Type

BathArray with shape (n)

data

Data stored in cube.

Type

ndarray with shape (size[0], size[1], size[2]

grid

Coordinates of the points at which data is computed.

Type

ndarray with shape (size[0], size[1], size[2], 3

integral

Data integrated over cube.

Type

float

spin

integral / 2 - total spin.

Type

float

transform(rotmatrix=None, shift=None)

Changes coordinates of the grid. DOES NOT ASSUME PERIODICITY.

Parameters
• rotmatrix (ndarray with shape (3, 3)) –

Rotation matrix R:

$\begin{split}R = &[n_1^{(1)} n_1^{(2)} n_1^{(3)}]\\ &[n_2^{(1)} n_2^{(2)} n_2^{(3)}]\\ &[n_3^{(1)} n_3^{(2)} n_3^{(3)}]\end{split}$

where $$n_i^{(j)}$$ corresponds to the coefficient of initial basis vector $$i$$ for $$j$$ new basis vector:

$e'_j = n_1^{(j)} \vec{e}_1 + n_2^{(j)} \vec{e}_2 + n_3^{(j)} \vec{e}_3$

In other words, columns of R are coordinates of the new basis in the old basis.

Given vector in initial basis v = [v1, v2, v3], vector in new basis is given as v’ = R.T @ v.

• shift (ndarray with shape (3,)) – Shift in the origin of coordinates (in the old basis).

integrate(position, gyro_n, gyro_e=- 17608.59705, spin=None, parallel=False, root=0)

Integrate over polarization data, stored in Cube object, to obtain hyperfine dipolar-dipolar tensor.

Parameters
• position (ndarray with shape (3,) or (n, 3)) – Position of the bath spin at which to compute hyperfine tensor or array of positions.

• gyro_n (float or ndarray with shape (n,)) – Gyromagnetic ratio of the bath spin or array of the ratios.

• gyro_e (float) – Gyromagnetic ratio of central spin.

• spin (float) – Total spin of the central spin. If not given, taken from the integral of the polarization.

Returns

Hyperfine tensor or array of hyperfine tensors.

Return type

ndarray with shape (3, 3) or (n, 3, 3)

### SpinDict and SpinType

Documentation for the SpinDict - dict-like class which describes the properties of the different types of the spins in the bath.

class SpinDict(*args, **kwargs)

Wrapper class for dictionary tailored for containing properties of the spin types. Can take np.void or BathArray instances as keys. Every entry is instance of the SpinType.

Each entry of the SpinDict can be initianlized as follows:

• As a Tuple containing name (optional), spin, gyromagnetic ratio, quadrupole constant (optional) and detuning (optional).

• As a SpinType instance.

Examples

>>> types = SpinDict()
>>> types['1H'] = ('1H', 1 / 2, 26.7519)
>>> types['2H'] = 1, 4.1066, 0.00286
>>> types['3H'] = SpinType('3H', 1 / 2, 28.535, 0)
>>> print(types)
SpinDict({'1H': (1H, 0.5, 26.7519, 0.0), '2H': (2H, 1, 4.1066, 0.00286), '3H': (3H, 0.5, 28.535, 0)})


If SpinType of the given bath spin is not provided, when requested SpinDict will try to find information about the bath spins in the common_isotopes.

If found, adds an entry to the given SpinDict instance and returns it. Otherwise KeyError is raised.

To initiallize several SpinType entries one can use add_types method.

Parameters
• *args – Any numbers of arguments which could initialize SpinType instances.

• **kwargs – Any numbers of keyword arguments which could initialize SpinType instances. For details see SpinDict.add_type method.

Add one or several spin types to the spin dictionary.

Parameters
• *args

Any numbers of arguments which could initialize SpinType instances. Accepted arguments:

• Tuple containing name, spin, gyromagnetic ratio, quadrupole constant (optional) and detuning (optional).

• SpinType instance.

Can also initialize one instance of SpinType if each argument corresponds to each positional argument necessary to initiallize.

• **kwargs – Any numbers of keyword arguments which could initialize SpinType instances. Usefull as an alternative for updating the dictionary. for each keyword argument adds an entry to the SpinDict with the same name as keyword.

Examples

>>> types = SpinDict()
>>> types.add_type('1H', 1 / 2, 26.7519)
>>> types.add_type(('1H_det', 1 / 2, 26.7519, 10), ('2H', 1, 4.1066, 0.00286),
>>>                 SpinType('3H', 1 / 2, 28.535, 0), e=(1 / 2, 6.7283, 0))
>>> print(types)
SpinDict(1H: (1H, 0.5, 26.7519), 1H_det: (1H_det, 0.5, 26.7519, 10),
2H: (2H, 1, 4.1066, 0.00286), 3H: (3H, 0.5, 28.535), e: (e, 0.5, 6.7283))

class SpinType(name, s=0.0, gyro=0.0, q=0.0, detuning=0.0)

Class which contains properties of each spin type in the bath.

Parameters
• name (str) – Name of the bath spin.

• s (float) –

Total spin of the bath spin.

Default 0.

• gyro (float) –

Gyromagnetic ratio in rad * kHz / G.

Default 0.

• q (float) –

Quadrupole moment in barn (for s > 1/2).

Default 0.

• detuning (float) –

Energy detuning from the zeeman splitting in kHz, included as an extra $$+\omega \hat S_z$$ term in the Hamiltonian, where $$\omega$$ is the detuning.

Default 0.

name

Name of the bath spin.

Type

str

s

Total spin of the bath spin.

Type

float

dim

Spin dimensionality = 2s + 1.

Type

int

gyro

Gyromagnetic ratio in rad/(ms * G).

Type

float

q

Quadrupole moment in barn (for s > 1/2).

Type

float

detuning

Energy detuning from the zeeman splitting in kHz.

Type

float

property h

Dictionary with additional spin Hamiltonian parameters. Key denotes the product of spin operators as:

Either a string containing x, y, z, +, - where each symbol is a corresponding spin operator:

• x == $$S_x$$

• y == $$S_y$$

• z == $$S_z$$

• p == $$S_+$$

• m == $$S_-$$

Several symbols is a product of those spin operators.

Or a tuple with indexes (k, q) for Stevens operators (see https://www.easyspin.org/documentation/stevensoperators.html).

The item is the coupling parameter in float.

Examples

• d['pm'] = 2000 corresponds to the Hamiltonian term $$\hat H_{add} = A \hat S_+ \hat S_-$$ with $$A = 2$$ MHz.

• d[2, 0] = 1.5e6 corresponds to Stevens operator $$B^q_k \hat O^q_k = 3 \hat S_z - s(s+1) \hat I$$ with $$k = 2$$, $$q = 0$$, and $$B^q_k = 1.5$$ GHz.

Type

dict

common_isotopes = SpinDict(1H: (0.5, 26.7522), 2H: (1.0, 4.1066, 0.0029), 3He: (0.5, -20.3789), ...)

An instance of the SpinDict dictionary, containing properties for the most of the common isotopes with nonzero spin. The isotope is considered common if it is stable and has nonzero concentration in nature.

Type

SpinDict

common_concentrations = {element ('H', 'He',...) : { isotope ('1H', '2H', ..) : concentration}}

Nested dict containing natural concentrations of the stable nuclear isotopes.

Type

dict

## Random bath

Documentation for the pycce.random_bath function, used to generate random bath.

random_bath(names, size, number=1000, density=None, types=None, density_units='cm-3', center=None, seed=None)

Generate random bath containing spins with names provided with argument name in the box of size size. By default generates coordinates in range (-size/2; +size/2) but this behavior can be changed by providing center keyword.

Examples

Generate 2000 $$^{13}\mathrm{C}$$ nuclear spins in the cubic box with the side of 100 angstrom:

>>> atoms = random_bath('13C', 100, number=2000, seed=10)
>>> print(atoms.size)
2000
>>> print(round(atoms.x.min()), round(atoms.x.max()))
-50.0 50.0


Generate electron spin bath with density $$10^{17} \mathrm{cm}^{-3}$$ in the cuboid box:

>>> electrons = random_bath('e', [1e3, 2e3, 3e3], density=1e17,
>>>                         density_units='cm-3', seed=10)
>>> print(electrons.size, round(electrons.x.min()), round(electrons.x.max()))
600 -494.0 500.0
>>> print(electrons.types)
SpinDict(e: (e, 0.5, -17608.59705))

Parameters
• names (str or array-like with length n) – Name of the bath spin or array with the names of the bath spins,

• size (float or ndarray with shape (3,)) – Size of the box. If float is given, assumes 3D cube with the edge = size. Otherwise the size specifies the dimensions of the box. Dimensionality is controlled by setting entries of the size array to 0.

• number (int or array-like with length n) – Number of the bath spins in the box or array with the numbers of the bath spins. Has to have the same length as the name array.

• density (float or array-like with length n) – Concentration of the bath spin or array with the concentrations. Has to have the same length as the name array.

• types (SpinDict) – Dictionary with SpinTypes or input to create one.

• density_units (str) –

If number of spins provided as density, defines units. Values are accepted in the format m, or m^x or m-x where m is the length unit, x is dimensionality of the bath (e.g. x = 1 for 1D, 2 for 2D etc). If only m is provided the dimensions are inferred from size argument. Accepted length units:

• m meters;

• cm centimeters;

• a angstroms.

• center (ndarray with shape (3,)) – Coordinates of the (0, 0, 0) point of the final coordinate system in the initial coordinates. Default is size / 2 - center is in the middle of the box.

• seed (int) – Seed for random number generator.

Returns

Array of the bath spins with random positions.

Return type

BathArray with shape (np.prod(number),)

## BathCell

Documentation for the pycce.BathCell - class for convenient generation of BathArray and the necessary helper functions.

class BathCell(a=None, b=None, c=None, alpha=None, beta=None, gamma=None, angle='rad', cell=None)

Generator of the bath spins positions from the unit cell of the material.

Parameters
• a (float) – a parameter of the primitive cell.

• b (float) – b parameter of the primitive cell.

• c (float) – c parameter of the primitive cell.

• alpha (float) – $$\alpha$$ angle of the primitive cell.

• beta (float) – $$\beta$$ angle of the primitive cell.

• gamma (float) – $$\gamma$$ angle of the primitive cell.

• angle (str) – units of the $$\alpha$$, $$\beta$$, $$\gamma$$ angles. Can be either radians ('rad'), or degrees ('deg').

• cell (ndarray with shape (3, 3)) –

Parameters of the cell.

cell is 3x3 matrix with columns of coordinates of crystallographic vectors in the cartesian reference frame. See cell attribute.

If provided, overrides a, b, and c.

cell

Parameters of the cell. cell is 3x3 matrix with entries:

$\begin{split}[&[a_x\ b_x\ c_x]\\ &[a_y\ b_y\ c_y]\\ &[a_z\ b_z\ c_z]]\end{split}$

where a, b, c are crystallographic vectors and x, y, z are their coordinates in the cartesian reference frame.

Type

ndarray with shape (3, 3)

atoms

Dictionary containing coordinates and occupancy of each lattice site:

{atom_1: [array([x1, y1, z1]), array([x2, y2, z2])],
atom_2: [array([x3, y3, z3]), ...]}

Type

dict

isotopes

Dictionary containing spin types and their concentration for each lattice site type:

{atom_1: {spin_1: concentration, spin_2: concentration},
atom_2: {spin_3: concentration ...}}


where atom_i are lattice site types, and spin_i are spin types.

Type

dict

property zdir

z-direction of the reference cartesian coordinate frame in cell coordinates.

Type

ndarray

rotate(rotation_matrix)

Rotate the BathCell using the rotation matrix provided.

Parameters

rotation_matrix (ndarray with shape (3,)) – Rotation matrix R which rotates the old basis of the cartesian reference frame to the new basis.

set_zdir(direction, type='cell')

Set z-direction of the cell.

Parameters
• direction (ndarray with shape (3,)) – Direction of the z axis.

• type (str) – How coordinates in direction are stored. If type="cell", assumes crystallographic coordinates. If type="angstrom" assumes that z direction is given in the cartresian reference frame.

Add coordinates of the lattice sites to the unit cell.

Parameters
• *args (tuple) – List of tuples, each containing the type of atom N (str), and the xyz coordinates in the format (float, float, float): (N, [x, y, z]).

• type (str) –

Type of coordinates. Can take values of ['cell', 'angstrom'].

If type="cell", assumes crystallographic coordinates.

If type="angstrom" assumes that coordinates are given in the cartresian reference frame.

Returns

View of cell.atoms dictionary, where each key is the type of lattice site, and each value is the list of coordinates in crystallographic frame.

Return type

dict

Examples

>>> cell = BathCell(10)
>>> cell.add_atoms(('C', [0, 0, 0]), ('C', [5, 5, 5]), type='angstrom')
>>> cell.add_atoms(('Si', [0, 0.5, 0.]), type='cell')
>>> print(cell.atoms)
{'C': [array([0., 0., 0.]), array([0.5, 0.5, 0.5])], 'Si': [array([0. , 0.5, 0. ])]}


Add spins that can populate each lattice site type.

Parameters

*args (tuple or list of tuples) –

Each tuple can have any of the following formats:

• Name of the lattice site N (str), name of the spin X (str), concentration c (float, in decimal): (N, X, c).

• Isotope name X and concentration c: (X, c).

In this case, the name of the isotope is given in the format "{}{}".format(digits, atom_name) where digits is any set of digits 0-9, atom_name is the name of the corresponding lattice site. Convenient when generating nuclear spin bath.

Returns

View of cell.isotopes dictionary which contains information about lattice site types, spin types, and their concentrations:

{atom_1: {spin_1: concentration, spin_2: concentration},
atom_2: {spin_3: concentration ...}}


Return type

dict

Examples

>>> cell = BathCell(10)
>>> cell.add_atoms(('C', [0, 0, 0]), ('C', [5, 5, 5]), type='angstrom')
>>> cell.add_isotopes(('C', 'X', 0.001), ('13C', 0.0107))
>>> print(cell.isotopes)
{'C': {'X': 0.001, '13C': 0.0107}}


Generate supercell populated with spins.

Note

If isotopes were not provided, assumes the natural concentration of nuclear spin isotopes for each lattice site type. However, if any isotope concentration is provided, then uses only user-defined ones.

Parameters
• size (float) – Approximate linear size of the supercell. The generated supercell will have minimal distance between opposite sides larger than this parameter.

• add (tuple or list of tuples) – Tuple or list of tuples containing common_isotopes to add as a defect. Each tuple contains name of the new isotope and its coordinates in the cell basis: (isotope_name, x_cell, y_cell, z_cell).

• remove (tuple or list of tuples) – Tuple or list of tuples containing bath to remove in the defect. Each tuple contains name of the atom to remove and its coordinates in the cell basis: (atom_name, x_cell, y_cell, z_cell).

• seed (int) – Seed for random number generator.

• recenter (bool) – True if place approximate center of the supercell at (0,0,0). False if start supercell at (0, 0, 0). Default True.

Note

While add takes the spin name as an argument, remove takes the lattice site name.

Returns

Array of the spins in the given supercell.

Return type

BathArray

to_cartesian(coord)

Transform coordinates from crystallographic basis to the cartesian reference frame.

Parameters

coord (ndarray with shape (3,) or (n, 3)) – Coordinates in crystallographic basis or array of coordinates.

Returns

Cartesian coordinates in angstrom.

Return type

ndarray with shape (3,) or (n, 3)

to_cell(coord)

Transform coordinates from the cartesian coordinates of the reference frame to the cell coordinates.

Parameters

coord (ndarray with shape (3,) or (n, 3)) – Cartesian coordinates in angstrom or array of coordinates.

Returns

Coordinates in the cell basis.

Return type

ndarray with shape (3,) or (n, 3)

classmethod from_ase(atoms_object)

Generate BathCell instance from ase.Atoms object of Atomic Simulations Environment (ASE) package.

Parameters

atoms_object (Atoms) – Atoms object, used to generate new BathCell instance.

Returns

New instance of the BathCell with atoms read from ase.Atoms.

Return type

BathCell

Generate BathCell instance from ase.Atoms object of Atomic Simulations Environment (ASE) package.

Parameters

atoms_object (Atoms) – Atoms object, used to generate new BathCell instance.

Returns

New instance of the BathCell with atoms read from ase.Atoms.

Return type

BathCell

Generate a defect in the given supercell.

The defect will be located in the unit cell, located roughly in the middle of the supercell, generated by BathCell, such that (0, 0, 0) of cartesian reference frame is located at (0, 0, 0) position of this unit cell.

Parameters
• cell (ndarray with shape (3, 3)) – parameters of the unit cell.

• atoms (BathArray) – Array of spins in the supercell.

• add (tuple or list of tuples) – Add spin type(s) to the supercell at specified positions to create point defect. Each tuple contains name of the new isotope and its coordinates in the cell basis: (isotope_name, x_cell, y_cell, z_cell).

• remove (tuple or list of tuples) – Remove lattice site from the supercell at specified position to create point defect. Each tuple contains name of the atom to remove and its coordinates in the cell basis: (atom_name, x_cell, y_cell, z_cell)`.

Returns

Array of spins with the defect added.

Return type

BathArray