Grid¶
-
class
sisl.
Grid
(shape, bc=None, sc=None, dtype=None, geometry=None)¶ Bases:
sisl.supercell.SuperCellChild
Real-space grid information with associated geometry.
This grid object handles cell vectors and divisions of said grid.
- Parameters
shape (float or (3,) of int) – the shape of the grid. A
float
specifies the grid spacing in Angstrom, while a list of integers specifies the exact grid size.bc (list of int (3, 2) or (3, ), optional) – the boundary conditions for each of the cell’s planes. Default to periodic BC.
sc (SuperCell, optional) – the supercell that this grid represents. sc has precedence if both
geometry
and sc has been specified. Default to[1, 1, 1]
.dtype (numpy.dtype, optional) – the data-type of the grid, default to
numpy.float64
.geometry (Geometry, optional) – associated geometry with the grid. If sc has not been passed the supercell will be taken from this geometry.
Examples
>>> grid1 = Grid(0.1, sc=10) >>> grid2 = Grid(0.1, sc=SuperCell(10)) >>> grid3 = Grid(0.1, sc=SuperCell([10] * 3)) >>> grid1 == grid2 True >>> grid1 == grid3 True >>> grid = Grid(0.1, sc=10, dtype=np.complex128) >>> grid == grid1 False
Attributes
__dict__
__doc__
__hash__
__module__
__weakref__
list of weak references to the object (if defined)
Voxel cell size
The data-type of the grid (in str)
Data-type used in grid
Volume of the grid voxel elements
deprecated geometry
Grid shape in \(x\), \(y\), \(z\) directions
Total number of elements in the grid
Returns the inherent
SuperCell
objects volMethods
_ArgumentParser_args_single
()Returns the options for
Grid.ArgumentParser
in case they are the only options_Grid__sc_geometry_dict
()Internal routine for copying the SuperCell and Geometry
__abs__
()Take the absolute value of the grid \(|grid|\)
__add__
(other)Add two grid values (or add a single value to all grid values)
__delattr__
Implement delattr(self, name).
__dir__
Default dir() implementation.
__div__
(other)__eq__
(other)Whether two grids are commensurable (no value checks, only grid shape)
__format__
Default object formatter.
__ge__
Return self>=value.
__getattribute__
Return getattr(self, name).
__getitem__
(key)Grid value at key
__gt__
Return self>value.
__iadd__
(other)Add, in-place, values from another grid
__idiv__
(other)__imul__
(other)__init__
(shape[, bc, sc, dtype, geometry])Initialize self.
__init_subclass__
This method is called when a class is subclassed.
__isub__
(other)Subtract, in-place, values from another grid
__itruediv__
(other)__le__
Return self<=value.
__lt__
Return self<value.
__mul__
(other)__ne__
(other)Whether two grids are incommensurable (no value checks, only grid shape)
__new__
Create and return a new object.
__reduce__
Helper for pickle.
__reduce_ex__
Helper for pickle.
__repr__
Return repr(self).
__setattr__
Implement setattr(self, name, value).
__setitem__
(key, val)Updates the grid contained
__sizeof__
Size of object in memory, in bytes.
__str__
()String of object
__sub__
(other)Subtract two grid values (or subtract a single value from all grid values)
__subclasshook__
Abstract classes can override this to customize issubclass().
__truediv__
(other)_check_compatibility
(other, msg)Internal check for asserting two grids are commensurable
_compatible_copy
(other, *args, **kwargs)Internally used copy function that also checks whether the two grids are compatible
_copy_sub
(n, axis[, scale_geometry])_fill
(non_filled[, dtype])_fill_sc
(supercell_index)_index_shape
(shape)Internal routine for shape-indices
_index_shape_cuboid
(cuboid)Internal routine for cuboid shape-indices
_index_shape_ellipsoid
(ellipsoid)Internal routine for ellipsoid shape-indices
add_vacuum
(vacuum, axis)Add vacuum along the axis lattice vector
append
(other, axis)Appends other
Grid
to this grid along axisarea
(ax0, ax1)Calculate the area spanned by the two axis ax0 and ax1
average
(axis[, weights])Average grid values along direction axis.
copy
([dtype])Copy the object, possibly changing the data-type
cross_section
(idx, axis)Takes a cross-section of the grid along axis axis
fill
(val)Fill the grid with this value
index
(coord[, axis])Find the grid index for a given coordinate (possibly only along a given lattice vector axis)
index2xyz
(index)Real-space coordinates of indices related to the grid
index_fold
(index[, unique])Converts indices from any placement to only exist in the “primary” grid
index_truncate
(index)Remove indices from outside the grid to only retain indices in the “primary” grid
interp
(shape[, method])Interpolate grid values to a new grid
Return true if all cell vectors are linearly independent
mean
(axis[, weights])Average grid values along direction axis.
mgrid
(*slices)Return a list of indices corresponding to the slices
pyamg_boundary_condition
(A, b[, bc])Attach boundary conditions to the pyamg grid-matrix A with default boundary conditions as specified for this
Grid
pyamg_fix
(A, b, pyamg_indices, value)Fix values for the stencil to value.
pyamg_index
(index)Calculate pyamg matrix indices from a list of grid indices
pyamg_source
(b, pyamg_indices, value)Fix the source term to value.
read
(sile, *args, **kwargs)Reads grid from the
Sile
using read_gridremove
(idx, axis)Removes certain indices from a specified axis.
remove_part
(idx, axis, above)Removes parts of the grid via above/below designations.
sc_index
(*args, **kwargs)set_bc
([boundary, a, b, c])Set the boundary conditions on the grid
set_boundary
([boundary, a, b, c])Set the boundary conditions on the grid
set_boundary_condition
([boundary, a, b, c])Set the boundary conditions on the grid
set_geom
(geometry)deprecated set_geom
set_geometry
(geometry)Sets the
Geometry
for the grid.set_grid
(shape[, dtype])Create the internal grid of certain size.
set_nsc
(*args, **kwargs)Set the number of super-cells in the
SuperCell
objectset_sc
(sc)Overwrites the local supercell
set_supercell
(sc)Overwrites the local supercell
sub
(idx, axis)Retains certain indices from a specified axis.
sub_part
(idx, axis, above)Retains parts of the grid via above/below designations.
sum
(axis)Sum grid values along axis axis.
swapaxes
(a, b)Swap two axes in the grid (also swaps axes in the supercell)
topyamg
([dtype])Create a pyamg stencil matrix to be used in pyamg
write
(sile, *args, **kwargs)Writes grid to the
Sile
using write_grid-
DIRICHLET
= 3¶
-
NEUMANN
= 2¶
-
OPEN
= 4¶
-
PERIODIC
= 1¶
-
add_vacuum
(vacuum, axis)¶ Add vacuum along the axis lattice vector
-
area
(ax0, ax1)¶ Calculate the area spanned by the two axis ax0 and ax1
-
average
(axis, weights=None)[source]¶ Average grid values along direction axis.
- Parameters
axis (int) – unit-cell direction to average across
weights (array_like, optional) – the weights for the individual axis elements, if boolean it corresponds to 0 and 1 for false/true.
See also
numpy.average
for details regarding the weights argument
-
cross_section
(idx, axis)[source]¶ Takes a cross-section of the grid along axis axis
Remark: This API entry might change to handle arbitrary cuts via rotation of the axis
-
property
dcell
¶ Voxel cell size
-
property
dkind
¶ The data-type of the grid (in str)
-
property
dtype
¶ Data-type used in grid
-
property
dvolume
¶ Volume of the grid voxel elements
-
fill
(val)[source]¶ Fill the grid with this value
- Parameters
val (numpy.dtype) – all grid-points will have this value after execution
-
property
geom
¶ deprecated geometry
-
index
(coord, axis=None)[source]¶ Find the grid index for a given coordinate (possibly only along a given lattice vector axis)
- Parameters
coord ((:, 3) or float or Shape) – the coordinate of the axis. If a float is passed axis is also required in which case it corresponds to the length along the lattice vector corresponding to axis. If a Shape a list of coordinates that fits the voxel positions are returned (all internal points also).
axis (int, optional) – the axis direction of the index, or for all axes if none.
-
index2xyz
(index)[source]¶ Real-space coordinates of indices related to the grid
- Parameters
index (array_like) – indices for grid-positions
- Returns
coordinates of the indices with respect to this grid spacing
- Return type
-
index_fold
(index, unique=True)[source]¶ Converts indices from any placement to only exist in the “primary” grid
Examples
>>> grid = Grid([10, 10, 10]) >>> assert np.all(grid.index_fold([-1, -1, -1]) == 9)
- Parameters
index (array_like) – indices for grid-positions
unique (bool, optional) – if true the returned indices are made unique after having folded the index points
- Returns
all indices are then within the shape of the grid
- Return type
See also
index_truncate
truncate indices by removing indices outside the primary cell
-
index_truncate
(index)[source]¶ Remove indices from outside the grid to only retain indices in the “primary” grid
Examples
>>> grid = Grid([10, 10, 10]) >>> assert len(grid.index_truncate([-1, -1, -1])) == 0
- Parameters
index (array_like) – indices for grid-positions
- Returns
all indices are then within the shape of the grid (others have been removed
- Return type
See also
index_fold
fold indices into the primary cell
-
interp
(shape, method='linear', **kwargs)[source]¶ Interpolate grid values to a new grid
- Parameters
shape (int, array_like) – the new shape of the grid
method (str) – the method used to perform the interpolation, see
scipy.interpolate.interpn
for further details.**kwargs (dict) – optional arguments passed to the interpolation algorithm The interpolation routine is
scipy.interpolate.interpn
-
is_orthogonal
()¶ Return true if all cell vectors are linearly independent
-
mean
(axis, weights=None)¶ Average grid values along direction axis.
- Parameters
axis (int) – unit-cell direction to average across
weights (array_like, optional) – the weights for the individual axis elements, if boolean it corresponds to 0 and 1 for false/true.
See also
numpy.average
for details regarding the weights argument
-
classmethod
mgrid
(*slices)[source]¶ Return a list of indices corresponding to the slices
The returned values are equivalent to
numpy.mgrid
but they are returned in a (:, 3) array.
-
pyamg_boundary_condition
(A, b, bc=None)[source]¶ Attach boundary conditions to the pyamg grid-matrix A with default boundary conditions as specified for this
Grid
- Parameters
A (scipy.sparse.csr_matrix) – sparse matrix describing the grid
b (numpy.ndarray) – a vector containing RHS of \(A x = b\) for the solution of the grid stencil
bc (list of BC, optional) – the specified boundary conditions. Default to the grid’s boundary conditions, else bc must be a list of elements with elements corresponding to
Grid.PERIODIC
/Grid.NEUMANN
…
-
pyamg_fix
(A, b, pyamg_indices, value)[source]¶ Fix values for the stencil to value.
- Parameters
A (
csr_matrix
/csc_matrix
) – sparse matrix describing the LHS for the linear system of equationsb (numpy.ndarray) – a vector containing RHS of \(A x = b\) for the solution of the grid stencil
pyamg_indices (list of int) – the linear pyamg matrix indices where the value of the grid is fixed. I.e. the indices should correspond to returned quantities from pyamg_indices.
value (float) – the value of the grid to fix the value at
-
pyamg_index
(index)[source]¶ Calculate pyamg matrix indices from a list of grid indices
- Parameters
index ((:, 3) of int) – a list of indices of the grid along each grid axis
- Returns
linear indices for the matrix
- Return type
See also
index
query indices from coordinates (directly passable to this method)
mgrid
Grid equivalent to
numpy.mgrid
. Grid.mgrid returns indices in shapes (:, 3), contrary to numpy’snumpy.mgrid
:raises ValueError : if any of the passed indices are below 0 or above the number of elements per axis:
-
classmethod
pyamg_source
(b, pyamg_indices, value)[source]¶ Fix the source term to value.
- Parameters
b (numpy.ndarray) – a vector containing RHS of \(A x = b\) for the solution of the grid stencil
pyamg_indices (list of int) – the linear pyamg matrix indices where the value of the grid is fixed. I.e. the indices should correspond to returned quantities from pyamg_indices.
-
static
read
(sile, *args, **kwargs)[source]¶ Reads grid from the
Sile
using read_grid- Parameters
sile (Sile, str or pathlib.Path) – a
Sile
object which will be used to read the grid if it is a string it will create a new sile usingget_sile
.* (args passed directly to
read_grid(,**)
) –
-
remove
(idx, axis)[source]¶ Removes certain indices from a specified axis.
Works exactly opposite to
sub
.- Parameters
idx (array_like) – the indices of the grid axis axis to be removed
axis (int) – the axis segment from which we remove all indices idx
-
remove_part
(idx, axis, above)[source]¶ Removes parts of the grid via above/below designations.
Works exactly opposite to
sub_part
-
set_bc
(boundary=None, a=None, b=None, c=None)[source]¶ Set the boundary conditions on the grid
- Parameters
boundary ((3, 2) or (3, ) or int, optional) – boundary condition for all boundaries (or the same for all)
a (int or list of int, optional) – boundary condition for the first unit-cell vector direction
b (int or list of int, optional) – boundary condition for the second unit-cell vector direction
c (int or list of int, optional) – boundary condition for the third unit-cell vector direction
:raises ValueError : if specifying periodic one one boundary, so must the opposite side.:
-
set_boundary
(boundary=None, a=None, b=None, c=None)¶ Set the boundary conditions on the grid
- Parameters
boundary ((3, 2) or (3, ) or int, optional) – boundary condition for all boundaries (or the same for all)
a (int or list of int, optional) – boundary condition for the first unit-cell vector direction
b (int or list of int, optional) – boundary condition for the second unit-cell vector direction
c (int or list of int, optional) – boundary condition for the third unit-cell vector direction
:raises ValueError : if specifying periodic one one boundary, so must the opposite side.:
-
set_boundary_condition
(boundary=None, a=None, b=None, c=None)¶ Set the boundary conditions on the grid
- Parameters
boundary ((3, 2) or (3, ) or int, optional) – boundary condition for all boundaries (or the same for all)
a (int or list of int, optional) – boundary condition for the first unit-cell vector direction
b (int or list of int, optional) – boundary condition for the second unit-cell vector direction
c (int or list of int, optional) – boundary condition for the third unit-cell vector direction
:raises ValueError : if specifying periodic one one boundary, so must the opposite side.:
-
set_geometry
(geometry)[source]¶ Sets the
Geometry
for the grid.Setting the
Geometry
for the grid is a possibility to attach atoms to the grid.It is not a necessary entity, so passing None is a viable option.
-
set_nsc
(*args, **kwargs)¶ Set the number of super-cells in the
SuperCell
objectSee
set_nsc
for allowed parameters.See also
SuperCell.set_nsc
the underlying called method
-
set_sc
(sc)¶ Overwrites the local supercell
-
set_supercell
(sc)¶ Overwrites the local supercell
-
property
shape
¶ Grid shape in \(x\), \(y\), \(z\) directions
-
property
size
¶ Total number of elements in the grid
-
sub
(idx, axis)[source]¶ Retains certain indices from a specified axis.
Works exactly opposite to
remove
.- Parameters
idx (array_like) – the indices of the grid axis axis to be retained
axis (int) – the axis segment from which we retain the indices idx
-
sub_part
(idx, axis, above)[source]¶ Retains parts of the grid via above/below designations.
Works exactly opposite to
remove_part
-
sum
(axis)[source]¶ Sum grid values along axis axis.
- Parameters
axis (int) – unit-cell direction to sum across
-
swapaxes
(a, b)[source]¶ Swap two axes in the grid (also swaps axes in the supercell)
If
swapaxes(0,1)
it returns the 0 in the 1 values.- Parameters
b (a,) – axes indices to be swapped
-
topyamg
(dtype=None)[source]¶ Create a pyamg stencil matrix to be used in pyamg
This allows retrieving the grid matrix equivalent of the real-space grid. Subsequently the returned matrix may be used in pyamg for solutions etc.
The pyamg suite is it-self a rather complicated code with many options. For details we refer to pyamg.
- Parameters
dtype (numpy.dtype, optional) – data-type used for the sparse matrix, default to use the grid data-type
- Returns
scipy.sparse.csr_matrix – the stencil for the pyamg solver
numpy.ndarray – RHS of the linear system of equations
Examples
This example proves the best method for a variety of cases in regards of the 3D Poisson problem:
>>> grid = Grid(0.01) >>> A, b = grid.topyamg() # automatically setups the current boundary conditions >>> # add terms etc. to A and/or b >>> import pyamg >>> from scipy.sparse.linalg import cg >>> ml = pyamg.aggregation.smoothed_aggregation_solver(A, max_levels=1000) >>> M = ml.aspreconditioner(cycle='W') # pre-conditioner >>> x, info = cg(A, b, tol=1e-12, M=M)
See also
pyamg_index
convert grid indices into the sparse matrix indices for
A
pyamg_fix
fixes stencil for indices and fixes the source for the RHS matrix (uses
pyamg_source
)pyamg_source
fix the RHS matrix
b
to a constant valuepyamg_boundary_condition
setup the sparse matrix
A
to given boundary conditions (called in this routine)
-
write
(sile, *args, **kwargs)[source]¶ Writes grid to the
Sile
using write_grid- Parameters
sile (Sile, str or pathlib.Path) – a
Sile
object which will be used to write the grid if it is a string it will create a new sile usingget_sile