API — gyroid 0.3 documentation

### Navigation

- index
- modules |
- previous |
- gyroid 0.3 documentation »

# API

## `gyroid` Package

### gyroid

gyroid is a python package that generates symmetry adapted basis functions (SABF) based on the space group of a unit cell.

#### References

- Qin, J., PhD Thesis, advisor: D. C. Morse, 2009
- Ranjan, A., PhD Thesis, advisor: D. C. Morse, 2007
- Tyler, C. A., PhD Thesis, advisor: D. C. Morse, 2004
- Tyler, C. A.; Morse, D. C. Macromolecules, 2003, 36, 3764

## `basis` Module

### gyroid.basis

This module is the main module of the package, wherein `Basis` class abstractsa whole SABF set.

This module defines three classes: `Basis`, `StarSet`, `StarAtom`.

This module provides one function: `index_waves()`.

class `gyroid.basis.` `Basis`(group, grid)

  Bases: `object`

  Representation of a whole SABF set.

  The SABF set mainly depends on the type of unit cell (crystal system), the point group symmetries, and how the unit cell is discretized.

  `fft2sabf`(c_fft, grid)

    Project a set of FFT coefficients onto a set of SABF coefficients.

    Parameters: | c_fft (double numpy.array) – a set of FFT coefficients on a discretized unit cell grid – a `Grid` object
    Returns: | a set of coefficients for SABF.
    Return type: | a 1D double numpy.array

  `generate_structure`(real_grid, c)

    Generate structure without projecting SABF to FFT.

    Parameters: | real_grid (tuple with integers) – number of grids along each unit vectors of the unit cell in real space c (1D double numpy.array) – coefficients for SABF
    Returns: | real space structure constructed via SABF
    Return type: | double numpy.array object

    Note This method is much slower than `generate_structure_by_fft()`. Use it for debug only.

  `generate_structure_by_fft`(real_grid, c, grid)

    Generate structure by projecting SABF to FFT, and then perform an inverse FFT.

    Parameters: | real_grid (tuple with integers) – number of grids along each unit vectors of the unit cell in real space c (1D double numpy.array) – coefficients for SABF grid – a `Grid` object
    Returns: | real space structure constructed via SABF
    Return type: | double numpy.array object

  `sabf2fft`(c, fft_grid, grid)

    Project a set of SABF coefficients onto a set of FFT coefficients.

    Parameters: | real_grid (tuple with integers) – number of grids along each unit vectors of the unit cell in real space c (1D double numpy.array) – coefficients for SABF grid – a `Grid` object
    Returns: | a set of FFT coefficients on the discretized unit cell
    Return type: | double numpy.array

class `gyroid.basis.` `StarSet`(group, grid, Gsq)

  Bases: `object`

  A `StarSet` object is a collection of stars containing waves with same magnitude.

  Wave vectors with same magnitudes may form more than one closed stars open star pair. For example, for P6mm in a 32 x 32 grid HEXAGONAL unit cell, a collection of waves with same magnitudes is:

      [[ 8  8 7  7 5  5 3  3 0  0 -3 -3 -5 -5 -7 -7 -8 -8],
       [-3 -5 0 -7 3 -8 5 -8 7 -7  8 -5  8 -3  7  0  5  3]]

  It has two closed stars:

      [[ 8  8 5  5 3  3 -3 -3 -5 -5 -8 -8],
       [-3 -5 3 -8 5 -8  8 -5  8 -3  5  3]]

      [[7  7 0  0 -7 -7],
       [0 -7 7 -7  7  0]]

class `gyroid.basis.` `StarAtom`(grid, Gsq, waves, phases, iwaves=None, iphases=None)

  Bases: `object`

  A `StarAtom` object represents a closed star or an open star pair.

  For a closed star, when a wave vector G is in it, -G is also in it.

  For an open star pair, if a wave vector G is in the first star, the inverse vector -G must be found in the accompanying invert star.

  `f`(x, shape, c1, c2)

    Calculate the value of the SABF f(r) at position r.

    Parameters: | x (string) – a BRAVAIS type real space vector shape – a `Shape` object c1 (double) – the coefficient for SABF c2 – the coefficient for invert SABF. If the star is not an open star pair, it is ignored
    Returns: | the value of an SABF or two SABF if the star is an open star pair
    Return type: | tuple with two doubles

`gyroid.basis.` `index_waves`(w, waves)

  Find the index of wave in a list of waves.

  Parameters: | w (numpy.array row vector) – wave vector to be searched waves (numpy.array) – a collection of wave vectors, each row vector is a wave
  Returns: | index for a wave in the collection of waves
  Return type: | integer

## `common` Module

### gyroid.common

This moudle define all global constants.

It includes:

    EPS, SMALL, LARGE
    BRAVAIS, CARTESIAN
    LAMELLAR
    SQUARE, RECTANGULAR, HEXAGONAL, OBLIQUE
    CUBIC, TETRAGONAL, ORTHORHOMBIC, TRIGONAL, MONOCLINIC, TRICLINIC
    DEFAULT
    CRYSTAL_SYSTEM1, CRYSTAL_SYSTEM2, CRYSTAL_SYSTEM3
    HM_ITA_TABLE1, HM_ITA_TABLE2, HM_ITA_TABLE3
    GROUP_ORDER_TABLE1, GROUP_ORDER_TABLE2, GROUP_ORDER_TABLE3

## `grid` Module

### gyroid.grid

class `gyroid.grid.` `Grid`(ngrid, g, lowBZ=-1, highBZ=1)

  Bases: `object`

  A `Grid` object represents a Discretized unit cell in reciprocal space.

  `is_wave_cancel`(G, g)

    Check whether the wave vector is canceled.

    A wave is canceled if and only if following conditions are met:

    1. Leaves G invariant (i.e. G . R == G)
    2. Produces a non-zero phase, such that G . t % 1.0 != 0

    Parameters: | G (numpy.array) – a wave vector g – a `Group` object
    Return type: | True or False

  `max_Gsq`

    The maximun square of wave vector in the grid.

  `to_BZ`(G)

    Shift a wave vector to the first Brillouin Zone (BZ).

    Parameters: | G (numpy.array) – a wave vector
    Returns: | wave vector in BZ and its square magnitude.

`gyroid.grid.` `wave_norm`(G, shape)

  Calculate the square magnitude of a wave vector G ^2.

  Parameters: | G (1D numpy.array) – a wave vector with 1, 2, or 3 elements shape – a `Shape` object
  Returns: | G ^2
  Return type: | double

## `group` Module

### gyroid.group

class `gyroid.group.` `Group`(dim, basis_type, shape_matrix, HM_symbol=None, ITA_number=None)

  Bases: `object`

  A `Group` object is a representaion of a space group.

  All symmetries in a space group must have the same basis type, i.e. they must all be either the BRAVAIS or the CARTESIAN bases.

  The space group is constructed either by providing a Hermann-Mauguin Symbol (HM_symbol) or a sequential number as given in the International Tables for Crystallography, Vol. A (ITA_number)

  Members : | dim, type, shape, symm

class `gyroid.group.` `CayleyTable`(symm=None)

  Bases: `object`

  Make a full Cayley table from a list of `Symmetry` objects.

  `update`(symm)

    Update the `CayleyTable` object.

    Currently, len(symm) must be larger than self.order.

## `space_group` Module

### gyroid.space_group

`gyroid.space_group.` `symmetry_generator1`(ITA_number, b, h)

  Output 1D space point group symmetry generators.

  There are 2 1D space groups. Currently, all 1D space groups are supported:

      [1, 2]

  Parameters: | ITA_number (integer) – 1 for P1, 2 for P-1 b (string) – basis type h (`Shape`) – the shape of a unit cell
  Returns: | the minimun number of symmetries which can be further expanded to the full set of point group symmetries
  Return type: | a list of `Symmetry` objects

`gyroid.space_group.` `symmetry_generator2`(ITA_number, b, h)

  Output 2D space point group symmetry generators.

  There are 17 2D space groups. Currently, Only following 2D space groups are supported:

      [1,2,3,4,5,6,17]

  Parameters: | ITA_number (integer) – a sequential number as given in the International Tables for Crystallography, Vol. A, allowed range [1,17] b (string) – basis type h (`Shape`) – the shape of a unit cell
  Returns: | the minimun number of symmetries which can be further expande to the full set of point group symmetries
  Return type: | a list of `Symmetry` objects

`gyroid.space_group.` `symmetry_generator3`(ITA_number, b, h)

  Output 3D space point group symmetry generators.

  There are 230 3D space groups. The symmetry generators can be found at http://cryst.ehu.es/cryst/get_gen.html. Currently, the supported 3D space groups are:

      [183, 229, 230]

  Parameters: | ITA_number (integer) – a sequential number as given in the International Tables for Crystallography, Vol. A, allowed range [1,17] b (string) – basis type h (`Shape`) – the shape of a unit cell
  Returns: | the minimun number of symmetries which can be further expande to the full set of point group symmetries
  Return type: | a list of `Symmetry`

## `symmetry` Module

### gyroid.symmetry

class `gyroid.symmetry.` `Symmetry`(dim, basis_type, shape, R=None, t=None)

  Bases: `object`

  A `Symmetry` object represents a point group symmetry element in a group.

  The basis type of a symmetry element should be either BRAVAIS or CARTESIAN.

  A symmetry element contains a point group matrix R and a translational vector t.

  `inverse`()

    Inverse the symmetry element (both R and t)

    Returns: | the inverse symmetry element of the current object
    Return type: | `Symmetry`

## `unitcell` Module

### gyroid.unitcell

Define a standard unit cell and its (real space) lattice basis vectors according to the cystal system.

class `gyroid.unitcell.` `UnitCell`(dim, cell_type='Default', cell_param=None)

  Bases: `object`

  A `UnitCell` object contains the shape information of a unit cell.

  All standard crystal systems in 1D, 2D and 3D spaces are supported.

  To construct a unit cell of a standard crystal system, one should provide the space dimension, the name of the standard crystal system, and the cell parameters (the lengths of each unit vectors in the unit cell, and the angles between the unit vectors).

  The name of the standard crystal system is best given by first import the gyroid.common module, and use the constant therein. However, you can also input a string, such as ‘Cubic’ for 3D cubic crystal systems. If the name of the crystal system is not given, it will use the default crystal system for each space dimension, and the cell parameters given by the user will be discarded.

  The default unit cell in 1D space is LAMELLAR, unit vector length is 1.0. The default unit cell in 2D space is SQUARE, unit vector length is 1.0. The default unit cell in 3D space is CUBIC, unit vector length is also 1.0.

class `gyroid.unitcell.` `Shape`(dim, a1, a2=None, a3=None)

  Bases: `object`

  A `Shape` object fully describes the shape of a unit cell.

  The heart of a `Shape` object is a shape matrix which can be constructed from unit vectors of a unit cell in Cartesian Coordinate.

  The Morse convention is used to construct the shape matrix. That is each row in the shape matrix represents a unit vector, e.g.:

      h = [a1 a2 a3
           b1 b2 b3
           c1 c2 c3]

  where a_i, b_i, c_i are the i th elements of unit vectors a, b, and c in the Bravis lattice in real space.

  `g`

    The shape matrix in reciprocal space.

  `h`

    The shape matrix in real space.

  `l`

    (a,b,c), the length vectors of each dimension.

  `shift`(t, basis_type)

    Shift position or translation vector so as to lie in the first unit cell.

    Parameters: | t (1D numpy.array) – translational or positional vector to be shifted. basis_type (string) – the type of the unit vector, can be either BRAVAIS or CARTESIAN
    Returns: | shifted translational or positional vector
    Return type: | 1D numpy.array

## `util` Module

### gyroid.util

`gyroid.util.` `render_structure_1d`(basis, grid, Na, c, save_data=True, data_name='struct1d.mat', save_img=True, show_img=True, img_name='struct1d.png', **kwargs)

  Calculate and render 1D structure for given SABF and unit cell.

  Parameters: | basis (`Basis`) – a set of SABFs Na (integer) – number of grids in a of the unit cell. c (1D numpy.array) – coefficients for each SABF save_data (bool) – if True, save data in file with Matlab mat format data_name (string) – the file name of the data file save_img (bool) – if True, save image in file, the format is determined by the extension of the image file name img_name (string) – the file name of the image file show_img (bool) – if True, show image on the screen kwargs – any extra key words arguments will be passed to plot functions

`gyroid.util.` `render_structure_2d`(basis, grid, Na, Nb, c, save_data=True, data_name='struct2d.mat', save_img=True, show_img=True, img_name='struct2d.png', levels=None, cmap=None, **kwargs)

  Calculate and render 2D structure for given SABF and unit cell.

  Parameters: | basis (`Basis`) – a set of SABFs Na (integer) – number of grids in a of the unit cell. Nb (integer) – number of grids in b of the unit cell. c (1D numpy.array) – coefficients for each SABF save_data (bool) – if True, save data in file with Matlab mat format data_name (string) – the file name of the data file save_img (bool) – if True, save image in file, the format is determined by the extension of the image file name img_name (string) – the file name of the image file show_img (bool) – if True, show image on the screen kwargs – any extra key words arguments will be passed to plot functions

`gyroid.util.` `render_structure_3d`(basis, grid, Na, Nb, Nc, c, save_data=True, data_name='struct3d.mat', save_img=True, show_img=True, img_name='struct3d.png', levels=None, cmap=None, **kwargs)

  Calculate and render 3D structure for given SABF and unit cell.

  Parameters: | basis (`Basis`) – a set of SABFs Na (integer) – number of grids in a of the unit cell. Nb (integer) – number of grids in b of the unit cell. Nc (integer) – number of grids in c of the unit cell. c (1D numpy.array) – coefficients for each SABF save_data (bool) – if True, save data in file with Matlab mat format data_name (string) – the file name of the data file save_img (bool) – if True, save image in file, the format is determined by the extension of the image file name img_name (string) – the file name of the image file show_img (bool) – if True, show image on the screen kwargs – any extra key words arguments will be passed to plot functions

`gyroid.util.` `prepare_scft_input`(dim, grid_num_vec, cryst_system, cryst_param_vec, sym_group, basis_grid_vec, basis_c, data_file='field_in.mat', show_img=False, save_img=False, img_file='field_in.png', **kwargs)