abipy.core package

Core objects.

Submodules

abipy.core.abinit_units module

This module defines constants and conversion factors matching those present in abinit that can be used when it is important to preserve consistency with the results produced by abinit.

abipy.core.abinit_units.phfactor_ev2units(units)

Return conversion factor eV –> units for phonons (case-insensitive)

Return type:

float

abipy.core.abinit_units.phunit_tag(units, unicode=False)

Mainly used for phonons. Return latex string from units. If unicode is True, replace Latex superscript with unitcode.

Return type:

str

abipy.core.abinit_units.wlabel_from_units(units, unicode=False)

Return latex string for phonon frequencies in units.

Return type:

str

abipy.core.abinit_units.phdos_label_from_units(units, unicode=False)

Return latex string for phonon DOS values in units.

Return type:

str

abipy.core.abinit_units.s2itup(comp)

Convert string in the form xx, xyz into tuple of two (three) indices that can be used to slice susceptibility tensors (numpy array).

Return type:

tuple

>>> assert s2itup("yy") == (1, 1)
>>> assert s2itup("xyz") == (0, 1, 2)

abipy.core.abinit_units.itup2s(t)

Convert tuple of 2 (3) integers into string in the form xx (xyz). Assume C-indexing e.g. 0 –> x

Return type:

str

>>> assert itup2s((0, 1)) == "xy"
>>> assert itup2s((0, 1, 2)) == "xyz"

abipy.core.atom module

This module provides objects and helper functions for atomic calculations.

class abipy.core.atom.NlkState(n: int, l: int, k: int | None = None)

Bases: NlkState

Named tuple storing (n, l) or (n, l, k) if relativistic pseudos. k is set to None if we are in non-relativistic mode.

classmethod from_nlkap(n, l, kap)

Return type:

NlkState

property latex: str

property latex_l: str

property ksign: str

property j: int

Total angular momentum

as_dict()

Makes Nlk obey the general json interface used in pymatgen for easier serialization.

Return type:

dict

get_dict4pandas()

Dictionary used to build pandas DataFrames.

Return type:

dict

from_dict(d)

Reconstruct object from the dictionary in MSONable format produced by as_dict.

Return type:

NlkState

class abipy.core.atom.QState(n: int, l: int, occ: float, eig: float | None = None, j: int | None = None, s: int | None = None)

Bases: QState

This object collects the set of quantum numbers and the physical properties associated to a single electron in a spherically symmetric atom.

property has_j: bool

property has_s: bool

class abipy.core.atom.AtomicConfiguration(Z, states)

Bases: object

Atomic configuration of an all-electron atom.

classmethod from_string(Z, string, has_s=False, has_j=False)

Return type:

AtomicConfiguration

classmethod neutral_from_symbol(symbol)

Return type:

AtomicConfiguration

symbol: str or int

Can be a chemical symbol (str) or an atomic number (int).

copy()

Shallow copy of self.

Return type:

AtomicConfiguration

property symbol: str

Chemical symbol

property spin_mode: str

Spin-unpolarized calculation. polarized: Spin-polarized calculation.

Type:

unpolarized

property echarge: float

Electronic charge (float < 0 ).

property isneutral: bool

True if self is a neutral configuration.

add_state(**qnumbers)

Add a list of QState instances to self.

Return type:

None

remove_state(**qnumbers)

Remove a quantum state from self.

Return type:

None

class abipy.core.atom.RadialFunction(name, rmesh, values)

Bases: object

A RadialFunction has a name, a radial mesh and values defined on this mesh.

classmethod from_filename(filename, rfunc_name=None, cols=(0, 1))

Initialize the object reading data from filename (txt format).

Parameters:

• filename (str) – Path to the file containing data.

• rfunc_name – Optional name for the RadialFunction (defaults to filename)

• cols – List with the index of the columns containing the radial mesh and the values.

Return type:

RadialFunction

property to_dict: dict

pprint(what='rmesh+values', stream=None)

pprint method (useful for debugging)

Return type:

None

property rmax: float

Outermost point of the radial mesh.

property rsize: float

Size of the radial mesh.

property minmax_ridx: tuple[int, int]

Returns the indices of the values in a list with the maximum and minimum value.

property inodes: list[int]

” List with the index of the nodes of the radial function.

property spline

Cubic spline.

property roots

Return the zeros of the spline.

get_peaks(**kwargs)

derivatives(r)

Return all derivatives of the spline at the point r.

integral()

Cumulatively integrate y(x) using the composite trapezoidal rule.

Return type:

RadialFunction

Returns:

Function1d with \(\int y(x) dx\)

integral3d(a=None, b=None)

Return definite integral of the spline of (r**2 values**2) between two given points a and b

Parameters:

• a – First point. rmesh[0] if a is None

• b – Last point. rmesh[-1] if a is None

ifromr(rpoint)

The index of the point in the radial mesh.

Return type:

int

ir_small(abs_tol=0.01)

Returns the rightmost index where the abs value of the wf becomes greater than abs_tol

Parameters:

abs_tol (float) – Absolute tolerance.

Return type:

int

Warning

Assumes that self.values are tending to zero for r –> infinity.

r2f2_integral()

Cumulatively integrate r**2 f**2(r) using the composite trapezoidal rule.

r2f_integral()

Cumulatively integrate r**2 f(r) using the composite trapezoidal rule.

get_intr2j0(ecut, numq=3001)

Compute 4piint[(frac{sin(2pi q r)}{2pi q r})(r^2 n(r))dr].

class abipy.core.atom.RadialWaveFunction(nlk, name, rmesh, values)

Bases: RadialFunction

Extends RadialFunction adding info on the set of quantum numbers. and methods specialized for electronic wavefunctions.

abipy.core.fields module

This module contains the class describing densities in real space on uniform 3D meshes.

class abipy.core.fields.Density(nspinor, nsppol, nspden, datar, structure, iorder='c')

Bases: _DensityField

Electronic density.

Note

Unlike in Abinit, datar[nspden] contains the up/down components if nsppol = 2

Inheritance Diagram

netcdf_name = 'density'

latex_label = 'Density [$e/A^3$]'

classmethod ae_core_density_on_mesh(valence_density, structure, rhoc, maxr=2.0, nelec=None, tol=0.01, method='get_sites_in_sphere', small_dist_mesh=(8, 8, 8), small_dist_factor=1.5)

Initialize the all electron core density of the structure from the pseudopotentials rhoc files. For points close to the atoms, the value at the grid point would be defined as the average on a finer grid in the neghibourhood of the point.

Parameters:

• valence_density – a Density object representing the valence charge density

• structure – the structure for which the total core density will be calculated

• rhoc – rhoc files for the elements in structure. Can be a list with len=len(structure) or a dictionary {element: rhoc}. Distances should be in Angstrom and densities in e/A^3.

• maxr – maximum radius for the distance between grid points and atoms.

• nelec – if given a check will be performed to verify that the integrated density will be within 1% error with respect to nelec. The total density will also be rescaled to fit exactly the given number.

• tol – tolerance above which the system will raise an exception if the integrated density doesn’t sum up to the value specified in nelec. Default 0.01 (1% error).

• method –

  different methods to perform the calculation:

  • get_sites_in_sphere: based on Structure.get_sites_in_sphere.

  • mesh3d_dist_gridpoints: based on Mesh3D.dist_gridpoints_in_spheres. Generally faster than

    get_sites_in_sphere, but tests can be made for specific cases.

  • get_sites_in_sphere_legacy: as get_sites_in_sphere, but part of the procedure is not vectorized

  • mesh3d_dist_gridpoints_legacy: as mesh3d_dist_gridpoints, but part of the procedure is not vectorized

• small_dist_mesh – defines the finer mesh.

• small_dist_factor – defines the maximum distance for which a point should be considered close enough to switch to the finer grid method. Note that this is a factor, the distance is defined with respect to the size of the cell.

get_nelect(spin=None)

Returns the number of electrons with given spin.

If spin is None, the total number of electrons is computed.

property total_rhor: ndarray

numpy.ndarray with the total density in real space on the FFT mesh.

total_rhor_as_density()

Return a Density object with the total density.

property total_rhog: ndarray

numpy.ndarray with the total density in G-space.

property magnetization_field: ndarray

numpy.ndarray with the magnetization field in real space on the FFT mesh:

• 0 if spin-unpolarized calculation

• spin_up - spin_down if collinear spin-polarized

• numpy array with (mx, my, mz) components if non-collinear magnetism

property magnetization

Magnetization field integrated over the unit cell. Scalar if collinear, vector with (mx, my, mz) components if non-collinear.

property nelect_updown: tuple

Tuple with the number of electrons in the up/down channel. Return (None, None) if non-collinear.

property zeta: ndarray

numpy.ndarray with Magnetization(r) / total_density(r)

export_to_cube(filename, spin='total')

Export real space density to CUBE file filename.

Return type:

None

classmethod from_cube(filename, spin='total')

Read real space density to CUBE file filename. Return new Density instance.

to_chgcar(filename=None)

Convert a Density object into a Chgar object. If filename is not None, density is written to this file in Chgar format

Return type:

Chgcar

Returns:

Chgcar instance.

Note

From: http://cms.mpi.univie.ac.at/vasp/vasp/CHGCAR_file.html:

This file contains the total charge density multiplied by the volume For spinpolarized calculations, two sets of data can be found in the CHGCAR file. The first set contains the total charge density (spin up plus spin down), the second one the magnetization density (spin up minus spin down). For non collinear calculations the CHGCAR file contains the total charge density and the magnetisation density in the x, y and z direction in this order.

classmethod from_chgcar_poscar(chgcar, poscar)

Build a :class`Density` object from Vasp data.

Parameters:

• chgcar – Either string with the name of a CHGCAR file or Chgcar pymatgen object.

• poscar – Either string with the name of a POSCAR file or Poscar pymatgen object.

class abipy.core.fields.VxcPotential(nspinor, nsppol, nspden, datar, structure, iorder='c')

Bases: _PotentialField

XC Potential.

Inheritance Diagram

netcdf_name = 'exchange_correlation_potential'

latex_label = 'vxc $[eV/A^3]$'

class abipy.core.fields.VhartreePotential(nspinor, nsppol, nspden, datar, structure, iorder='c')

Bases: _PotentialField

Hartree Potential.

Inheritance Diagram

netcdf_name = 'vhartree'

latex_label = 'vh $[eV/A^3]$'

class abipy.core.fields.VhxcPotential(nspinor, nsppol, nspden, datar, structure, iorder='c')

Bases: _PotentialField

Hartree + XC

Inheritance Diagram

netcdf_name = 'vhxc'

latex_label = 'vhxc $[eV/A^3]$'

class abipy.core.fields.VksPotential(nspinor, nsppol, nspden, datar, structure, iorder='c')

Bases: _PotentialField

Hartree + XC + sum of local pseudo-potential terms.

Inheritance Diagram

netcdf_name = 'vtrial'

latex_label = 'vks $[eV/A^3]$'

abipy.core.func1d module

Function1D describes a function of a single variable and provides an easy-to-use API for performing common tasks such as algebraic operations, integrations, differentiations, plots, etc.

class abipy.core.func1d.Function1D(mesh, values)

Bases: object

Immutable object representing a real|complex function of real variable.

classmethod from_constant(mesh, const)

Build a constant function from the mesh and the scalar const

Return type:

Function1D

classmethod from_func(func, mesh)

Initialize the object from a callable.

Example:

Function1D.from_func(np.sin, mesh=np.arange(1,10))

Return type:

Function1D

as_dict()

Makes Function1D obey the general json interface used in pymatgen for easier serialization.

Return type:

dict

classmethod from_dict(d)

Reconstruct object from the dictionary in MSONable format produced by as_dict.

Return type:

Function1D

classmethod from_file(path, comments='#', delimiter=None, usecols=(0, 1))

Initialize an instance by reading data from path (txt format) see also np.loadtxt()

Parameters:

• path – Path to the file containing data.

• comments – The character used to indicate the start of a comment; default: ‘#’.

• delimiter – str, optional The string used to separate values. By default, this is any whitespace.

• usecols – sequence, optional. Which columns to read, with 0 being the first. For example, usecols = (1,4) will extract data from the 2nd, and 5th columns.

Return type:

Function1D

property mesh: ndarray

numpy.ndarray with the mesh points

property values: ndarray

Values of the functions.

property real: Function1D

Return new Function1D with the real part of self.

property imag: Function1D

Return new Function1D with the imaginary part of self.

conjugate()

Return new Function1D with the complex conjugate.

Return type:

Function1D

abs()

Return Function1D with the absolute value.

Return type:

Function1D

to_file(path, fmt='%.18e', header='')

Save data in a text file. Use format fmr. A header is added at the beginning.

Return type:

None

has_same_mesh(other)

True if self and other have the same mesh.

Return type:

bool

property bma: float

Return b-a. f(x) is defined in [a,b]

property max: float

Max of f(x) if f is real, max of \(|f(x)|\) if complex.

property min: float

Min of f(x) if f is real, min of \(|f(x)|\) if complex.

property iscomplexobj: bool

Check if values is array of complex numbers. The type of the input is checked, not the value. Even if the input has an imaginary part equal to zero, np.iscomplexobj evaluates to True.

property h: float | None

The spacing of the mesh. None if mesh is not homogeneous.

property dx: ndarray

numpy.ndarray of len(self) - 1 elements giving the distance between two consecutive points of the mesh, i.e. dx[i] = ||x[i+1] - x[i]||.

find_mesh_index(value)

Return the index of the first point in the mesh whose value is >= value -1 if not found

Return type:

int

finite_diff(order=1, acc=4)

Compute the derivatives by finite differences.

Parameters:

• order (int) – Order of the derivative.

• acc (int) – Accuracy. 4 is fine in many cases.

Return type:

Function1D

Returns:

Function1D instance with the derivative.

integral(start=0, stop=None)

Cumulatively integrate y(x) from start to stop using the composite trapezoidal rule.

Return type:

Function1D

Returns:

Function1D with \(\int y(x) dx\)

property spline

Cubic spline with s=0

property spline_roots

Zeros of the spline.

spline_on_mesh(mesh)

Spline the function on the given mesh, returns Function1D object.

Return type:

Function1D

spline_derivatives(x)

Returns all derivatives of the spline at point x.

spline_integral(a=None, b=None)

Returns the definite integral of the spline of f between two given points a and b

Parameters:

• a – First point. mesh[0] if a is None

• b – Last point. mesh[-1] if a is None

property integral_value

Compute \(\int f(x) dx\).

property l1_norm: float

Compute \(\int |f(x)| dx\).

property l2_norm: float

Compute \(\sqrt{\int |f(x)|^2 dx}\).

fft()

Compute the FFT transform (negative sign).

Return type:

Function1D

ifft(x0=None)

Compute the FFT transform \(\int e+i\)

Return type:

Function1D

plot_ax(ax, exchange_xy=False, normalize=False, xfactor=1, yfactor=1, *args, **kwargs)

Helper function to plot self on axis ax.

Parameters:

• ax – matplotlib.axes.Axes.

• exchange_xy – True to exchange the axis in the plot.

• args – Positional arguments passed to ax.plot

• normalize – Normalize the ydata to 1.

• xfactor – xvalues and yvalues are multiplied by this factor before plotting.

• yfactor – xvalues and yvalues are multiplied by this factor before plotting.

• kwargs – Keyword arguments passed to matplotlib. Accepts

kwargs	Meaning
cplx_mode	string defining the data to print. Possible choices are (case-insensitive): re for the real part “im” for the imaginary part, “abs” for the absolute value. “angle” to display the phase of the complex number in radians. Options can be concatenated with “-”

Return type:

list

Returns:

List of lines added.

plot(ax=None, **kwargs)

Plot the function with matplotlib.

Parameters:

ax – matplotlib.axes.Axes or None if a new figure should be created.

kwargs	Meaning
exchange_xy	True to exchange x- and y-axis (default: False)

Returns: matplotlib.figure.Figure.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot. Default: None.
show	True to show the figure. Default: True.
savefig	“abc.png” or “abc.svg” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4).
tight_layout	True to call fig.tight_layout. Default: False.
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly: Default: False

Return type:

Any

plotly_traces(fig, rcd=None, exchange_xy=False, xfactor=1, yfactor=1, *args, **kwargs)

Helper function to plot the function with plotly.

Parameters:

• fig – plotly.graph_objects.Figure.

• rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the subplot in the grid.

• exchange_xy – True to exchange the x and y in the plot.

• xfactor – xvalues and yvalues are multiplied by this factor before plotting.

• yfactor – xvalues and yvalues are multiplied by this factor before plotting.

• args – Positional arguments passed to ‘plotly.graph_objects.Scatter’

• kwargs – Keyword arguments passed to ‘plotly.graph_objects.Scatter’. Accepts also AbiPy specific kwargs:

kwargs	Meaning
cplx_mode	string defining the data to print. Possible choices are (case-insensitive): re for the real part “im” for the imaginary part, “abs” for the absolute value. “angle” to display the phase of the complex number in radians. Options can be concatenated with “-”

plotly(exchange_xy=False, fig=None, rcd=None, **kwargs)

Plot the function with plotly.

Parameters:

• exchange_xy – True to exchange x- and y-axis (default: False)

• fig – plotly figure or None if a new figure should be created.

• rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the subplot in the grid.

Returns: plotly-Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
hovermode	True to show the hover info (default: False)
savefig	“abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file.
write_json	Write plotly figure to write_json JSON file. Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor
renderer	(str or None (default None)) – A string containing the names of one or more registered renderers (separated by “+” characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See <https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html>
config (dict)	A dict of parameters to configure the figure. The defaults are set in plotly.js.
chart_studio	True to push figure to chart_studio server. Requires authentication. Default: False.
template	Plotly template. See <https://plotly.com/python/templates> [“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”, “seaborn”, “simple_white”, “none”] Default is None that is the default template is used.

abipy.core.globals module

Global variables used to initialize AbiPy environment in notebooks.

abipy.core.globals.in_notebook()

True if we are running inside a jupyter notebook (and enable_notebook has been called).

Return type:

bool

abipy.core.globals.disable_notebook()

Set in_notebook flag to False.

Return type:

None

abipy.core.globals.enable_notebook(with_seaborn=True)

Set in_notebook flag to True and activate seaborn settings for notebooks if with_seaborn.

Return type:

None

abipy.core.globals.get_abinb_workdir()

Return the absolute path of the scratch directory used to produce and save temporary files when we are runnning inside a jupyter notebook.

Note

Due to web-browser policy, files used in the notebook must be within the current working directory.

Return type:

str

abipy.core.globals.abinb_mkstemp(force_abinb_workdir=False, use_relpath=False, **kwargs)

Invoke mkstep with kwargs, return the (fd, name) of the temporary file. kwargs are passed to mkstemp except for dir if we are inside a jupyter notebook.

Parameters:

• use_abipy_nbworkdir

• use_relpath – Return relative path (os.path.relpath) if True else absolute (default) Relative paths are required if we are gonna use the temporary file in notebooks or in web browers. In this case, the caller is responsbile for calling the function with the correct flag.

Return type:

tuple

_, filename = abinb_mkstep(suffix="." + ext, text=True)

abipy.core.globals.get_workdir(workdir)

Return temporary directory if workdir is None else workdir. Allow users to specify the temporary directory via ABIPY_TMPDIR env variable.

Return type:

str

abipy.core.gsphere module

This module contains the class defining the G-sphere for wavefunctions, densities and potentials

class abipy.core.gsphere.GSphere(ecut, lattice, kpoint, gvecs, istwfk=1)

Bases: Sequence

Descriptor-class for the G-sphere.

property gvecs: ndarray

numpy.ndarray with the G-vectors in reduced coordinates.

index(gvec)

return the index of the G-vector gvec in self. Raises: ValueError if the value is not present.

Return type:

int

count(gvec)

Return number of occurrences of gvec.

Return type:

int

copy()

shallow copy.

Return type:

GSphere

to_string(verbose=0)

String representation.

Return type:

str

zeros(dtype=<class 'float'>, extra_dims=())

Returns new zeroed 1D numpy.ndarray.

The type can be set with the dtype keyword. Extra dimensions can be added with extra_dims.

Return type:

ndarray

czeros(extra_dims=())

New zeroed 1D complex numpy.ndarray.

Return type:

ndarray

empty(dtype=<class 'float'>, extra_dims=())

Returns new uninitialized 1D numpy.ndarray.

The type can be set with the dtype keyword. Extra dimensions can be added with extra_dims.

Return type:

ndarray

cempty(extra_dims=())

Returns new uninitialized 1D complex numpy.ndarray.

Return type:

ndarray

tofftmesh(mesh, arr_on_sphere)

Insert the array arr_on_sphere given on the sphere inside the FFT mesh.

Parameters:

• mesh

• arr_on_sphere

Return type:

ndarray

fromfftmesh(mesh, arr_on_mesh)

Transfer arr_on_mesh given on the FFT mesh to the G-sphere.

Return type:

ndarray

abipy.core.irrepsdb module

abipy.core.kpoints module

This module defines objects describing the sampling of the Brillouin Zone.

abipy.core.kpoints.issamek(k1, k2, atol=None)

True if k1 and k2 are equal modulo a lattice vector. Use _ATOL_KDIFF is atol is None.

>>> assert issamek([1, 1, 1], [0, 0, 0])
>>> assert issamek([1.1, 1, 1], [0, 0, 0], atol=0.1)
>>> assert not issamek(0.00003, 1)

abipy.core.kpoints.wrap_to_ws(x)

Transforms x in its corresponding reduced number in the interval ]-1/2,1/2].

abipy.core.kpoints.wrap_to_bz(x)

Transforms x in its corresponding reduced number in the interval [0,1[.”

abipy.core.kpoints.as_kpoints(obj, lattice, weights=None, names=None)

Convert obj into a list of k-points.

Parameters:

• obj – Kpoint or list of Kpoint objects or array-like object.

• lattice – Reciprocal lattice.

• weights – k-point weights. Ignored if obj is already a Kpoint instance or a list of Kpoint items.

• name – string with the name of the k-point. Ignored if obj is already a Kpoint instance or a list of Kpoint items.

class abipy.core.kpoints.Kpoint(frac_coords, lattice, weight=None, name=None)

Bases: SlotPickleMixin

Class defining one k-point. This object is immutable and can be used as key in dictionaries

Note that we usually construct the object by passing pymatgen.reciprocal_lattice that is the standard reciprocal lattice used for solid state physics with a factor of 2 * pi i.e. a_i . b_j = 2pi delta_ij. Abinit, on the contrary, uses the crystallographic reciprocal lattice i.e. no 2pi factor. so pay attention when converting Abinit routines to AbiPy.

classmethod from_name_and_structure(name, structure)

Build Kpoint object from string with name and structure.

property frac_coords

Fractional coordinates of the k-points.

property lattice

pymatgen.core.lattice.Lattice object describing the Reciprocal lattice.

property weight

Weight of the k-point. 0.0 if the weight is not defined.

set_weight(weight)

Set the weight of the k-point.

property cart_coords

Cartesian coordinates of the k-point.

property name

Name of the k-point. None if not available.

set_name(name)

Set the name of the k-point.

Return type:

None

property on_border

True if the k-point is on the border of the BZ (lattice translations are taken into account).

tos(m='fract', scale=False)

Return string with fractional or cartesian coords depending on mode m in (“fract”, “cart”, “fracart”)

to_string(verbose=0)

String representation.

Return type:

str

classmethod as_kpoint(obj, lattice)

Convert obj into a Kpoint instance.

Parameters:

• obj – Kpoint instance or array-like with the reduced coordinates.

• lattice – pymatgen.core.lattice.Lattice object defining the reciprocal lattice.

classmethod gamma(lattice, weight=None)

Constructor for the Gamma point.

copy()

Deep copy.

is_gamma(allow_umklapp=False, atol=None)

Return True if this the gamma point.

Parameters:

• allow_umklapp – True if umklapp G-vectors are allowed.

• atol – Absolute tolerance for k-point comparison (used only if umklapp).

Return type:

bool

property norm

Norm of the kpoint.

versor()

Returns the versor i.e. math:||k|| = 1

wrap_to_ws()

Returns a new abipy.core.kpoints.Kpoint in the Wigner-Seitz zone.

wrap_to_bz()

Returns a new abipy.core.kpoints.Kpoint in the first unit cell.

compute_star(symmops, wrap_tows=True)

Return the star of the kpoint (tuple of abipy.core.kpoints.Kpoint objects).

Return type:

KpointStar

class abipy.core.kpoints.KpointList(reciprocal_lattice, frac_coords, weights=None, names=None, ksampling=None)

Bases: Sequence

Base class defining a sequence of abipy.core.kpoints.Kpoint objects. Essentially consists of base methods implementing the sequence protocol and helper functions. The subclasses abipy.core.kpoints.Kpath and abipy.core.kpoints.IrredZone provide specialized methods to operate on k-points representing a path or list of points in the IBZ, respectively. This object is immutable.

Inheritance Diagram

Error

alias of KpointsError

classmethod subclass_from_name(name)

Return the class with the given name.

classmethod from_dict(d)

Makes Kpoints obey the general json interface used in pymatgen for easier serialization.

as_dict()

Makes Kpoints obey the general json interface used in pymatgen for easier serialization.

property reciprocal_lattice

pymatgen.core.lattice.Lattice object defining the reciprocal lattice.

to_string(title=None, verbose=0, pre_string='')

String representation.

Return type:

str

index(kpoint)

Returns: the first index of kpoint in self.

Raises: ValueError if not found.

Return type:

int

get_all_kindices(kpoint)

Return numpy array with indexes of all the k-point Accepts: abipy.core.kpoints.Kpoint instance or integer.

find(kpoint)

Returns: first index of kpoint. -1 if not found

Return type:

int

count(kpoint)

Return number of occurrences of kpoint

find_closest(obj)

Find the closest k-point in the list (not necessarily equal).

Parameters:

obj – Fractional coordinates or abipy.core.kpoints.Kpoint instance.

Returns:

(ind, kpoint, dist)

where ind is the index in self of the closest k-point. kpoint is the abipy.core.kpoints.Kpoint instance of index ind. dist is the distance between obj and kpoint.

property is_path: bool

True if self represents a path in the BZ.

property is_ibz: bool

True if self represents a list of points in the IBZ.

property mpdivs_shifts

The Monkhorst-Pack (MP) divisions and shifts. Both quantities are set to None if self is not a MP mesh. Use is_mpmesh to check whether self is a MP mesh.

property is_mpmesh: bool

True if self represents a Monkhorst-Pack mesh. i.e if the sampling has been specified in terms of divisions along the reciprocal lattice vectors (ngkpt)

property frac_coords

Fractional coordinates of the k-point as numpy.ndarray of shape (len(self), 3)

get_cart_coords()

Cartesian coordinates of the k-point as numpy.ndarray of shape (len(self), 3)

property names: list[str]

List with the name of the k-points.

property weights: ndarray

numpy.ndarray with the weights of the k-points.

sum_weights()

Returns the sum of the weights.

check_weights()

Check if weights are normalized to one. Raises: ValueError if Weights are not normalized.

Return type:

None

get_highsym_datataframe(with_cart_coords=False)

Return pandas Dataframe with the names of the high-symmetry k-points and the reduced coordinates.

Parameters:

with_cart_coords – True to add extra column with the Cartesian coordinates.

Return: pandas.DataFrame

remove_duplicated()

Remove duplicated k-points from self. Returns new KpointList instance.

to_array()

Returns a numpy.ndarray [nkpy, 3] with the fractional coordinates.

to_json()

Returns a JSON string representation of the MSONable object.

Return type:

str

plot(ax=None, **kwargs)

Plot k-points with matplotlib.

plotly(fig=None, **kwargs)

Plot k-points with plotly.

get_k2kqg_map(qpt, atol_kdiff=None)

Compute mapping k_index –> (k + q)_index, g0

Parameters:

• qpt – q-point in fractional coordinate or Kpoint instance.

• atol_kdiff – Tolerance used to compare k-points. Use _ATOL_KDIFF is atol is None.

class abipy.core.kpoints.KpointStar(reciprocal_lattice, frac_coords, weights=None, names=None, ksampling=None)

Bases: KpointList

Star of the kpoint. Note that the first k-point is assumed to be the base of the star namely the point that is used to generate the Star.

Inheritance Diagram

property base_point

The point used to generate the star.

property name

The name of the star (inherited from the name of the base point).

class abipy.core.kpoints.Kpath(reciprocal_lattice, frac_coords, weights=None, names=None, ksampling=None)

Bases: KpointList

This object describes a k-path in reciprocal space. It provides methods to compute (line) derivatives along the path. The k-points do not have weights so Kpath should not be used to compute integral in the BZ.

Inheritance Diagram

classmethod from_structure(structure, line_density=20)

Return type:

Kpath

classmethod from_names(structure, knames, line_density=20)

Generate normalized K-path from list of k-point labels.

Parameters:

• structure – abipy.core.structure.Structure object.

• knames – List of strings with the k-point labels.

• line_density (int) – Number of points used to sample the smallest segment of the path

Return type:

Kpath

classmethod from_vertices_and_names(structure, vertices_names, line_density=20)

Generate normalized k-path from a list of vertices and the corresponding labels.

Parameters:

• structure – abipy.core.structure.Structure object.

• vertices_names – List of tuple, each tuple is of the form (kfrac_coords, kname) where kfrac_coords are the reduced coordinates of the k-point and kname is a string with the name of the k-point. Each point represents a vertex of the k-path.

• line_density (int) – Number of points used to sample the smallest segment of the path. If 0, use list of k-points given in vertices_names

Return type:

Kpath

to_string(verbose=0, title=None, **kwargs)

String representation.

Parameters:

verbose – Verbosity level. Default: 0

Return type:

str

property ds: ndarray

numpy.ndarray of len(self)-1 elements giving the distance between two consecutive k-points, i.e. ds[i] = ||k[i+1] - k[i]|| for i=0,1,…,n-1

property versors: tuple

Tuple of len(self) - 1 elements with the versors connecting k[i] to k[i+1].

property lines: list

Nested list containing the indices of the points belonging to the same line. Used for extracting the eigenvalues while looping over the lines.

Example

for line in kpath.lines:

vals_on_line = eigens[spin, line, band]

property frac_bounds: ndarray

Numpy array of shape [M, 3] with the vertices of the path in frac coords.

property cart_bounds: ndarray

Numpy array of shape [M, 3] with the vertices of the path in frac coords.

find_points_along_path(cart_coords, dist_tol=1e-12)

Find points in cart_coords lying on the path with distance less than dist_tol. See find_points_along_path function for API.

finite_diff(values, order=1, acc=4)

Compute the derivatives of values by finite differences.

Parameters:

• values – array-like object with shape=(nkpt) containing the values of the path.

• order (int) – Order of the derivative.

• acc (int) – Accuracy: 4 corresponds to a central difference with 5 points.

Returns:

ragged numpy array. The i-th entry is a numpy array with the derivatives on the i-th line.

class abipy.core.kpoints.IrredZone(reciprocal_lattice, frac_coords, weights=None, names=None, ksampling=None)

Bases: KpointList

Immutable sequence of points in the irreducible wedge of the BZ. Each point has a weight whose sum must equal 1 so that we can integrate quantities in the full Brillouin zone.

Note

Abinit supports different options for the specification of the BZ sampling:

• kptrlatt(3,3) or ngkpt(3) for the definition grid.

• shiftk(3, nshiftk) for the definition of multiple shifts.

• kptopt for the treatment of symmetry operations.

All these possibilities complicate the internal implementation in particular when we need to recostruct the full BZ and take into account the presence of multiple shifts since kptrlatt may have non-zero off-diagonal components. Client code that needs to know how the mesh was generated can rely on the following checks:

if not self.ibz: raise(“Need an IBZ sampling”)

mpdivs, shifts = self.mpdivs_shifts if mpdivs is None: raise ValueError(“Cannot handle kptrlatt with non-zero off-diagonal elements”) if len(shifts) > 1: raise ValueError(“Multiple shifts are not supported”) # Code for mesh defined in terms of mpdivs and one shift.

Inheritance Diagram

classmethod from_ngkpt(structure, ngkpt, shiftk, kptopt=1, spin_mode='unpolarized', verbose=0)

Build an IrredZone instance from (ngkpt, shift) by calling Abinit to get the list of IBZ k-points.

Return type:

IrredZone

classmethod from_kppa(structure, kppa, shiftk, kptopt=1, verbose=0)

Build an IrredZone instance from (kppa, shift) by calling Abinit to get the list of IBZ k-points.

Return type:

IrredZone

to_string(verbose=0, title=None)

String representation.

Return type:

str

abipy.core.kpoints.rc_list(mp, sh, pbc=False, order='bz')

Returns a numpy.ndarray with the linear mesh used to sample one dimension of the reciprocal space. Note that the coordinates are always ordered so that rc[i+1] > rc[i]. so that we can easily plot quantities defined on the 3D multidimensional mesh.

Parameters:

• mp – Number of Monkhorst-Pack divisions along this direction.

• sh – Shift

• pbc – if pbc is True, periodic boundary conditions are enforced.

• order – Possible values [“bz”, “unit_cell”]. if “bz”, the coordinates are forced to be in [-1/2, 1/2) if “unit_cell”, the coordinates are forced to be in [0, 1).

abipy.core.kpoints.kmesh_from_mpdivs(mpdivs, shifts, pbc=False, order='bz')

Returns a numpy.ndarray with the reduced coordinates of the k-points from the MP divisions and the shifts.

Parameters:

• mpdivs – The three MP divisions.

• shifts – Array-like object with the MP shift.

• pbc – If True, periodic images of the k-points will be included i.e. closed mesh.

• order – “unit_cell” if the kpoint coordinates must be in [0, 1) “bz” if the kpoint coordinates must be in [-1/2, +1/2)

class abipy.core.kpoints.Ktables(structure, mesh, is_shift, has_timrev)

Bases: object

Call spglib to compute the k-points in the IBZ with the corresponding weights as well as the mapping BZ –> IBZ.

Parameters:

• mesh

• is_shift

mesh

is_shift

ibz

nibz

weights

bz

nbz

grid

to_string(verbose=0, title=None, **kwargs)

String representation

Return type:

str

print_bz2ibz(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Print BZ –> IBZ mapping.

Return type:

None

abipy.core.kpoints.find_points_along_path(cart_bounds, cart_coords, dist_tol)

Find points in cart_coords lying on the path defined by cart_bounds. Result are ordered according to distance along the path.

Parameters:

• cart_bounds – [N, 3] array with the boundaries of the path in Cartesian coordinates.

• cart_coords – [M, 3] array with the points in Cartesian coordinate

• dist_tol – A point is considered to be on the path if its distance from the line is less than dist_tol.

Return: namedtuple with the following attributes:

(ikfound, dist_list, path_ticks)

ikfound is a numpy array with the indices of the points lying on the path. Empty if no point is found. dist_list: numpy array with the distance of the points along the line. path_ticks: numpy array with the ticks associated to the input k-path.

abipy.core.mesh3d module

This module contains the class defining Uniform 3D meshes.

class abipy.core.mesh3d.Mesh3D(shape, vectors)

Bases: object

Descriptor-class for uniform 3D meshes.

A Mesh3D object holds information on how functions, such as wave functions and electron densities, are discretized in a certain domain in space. The main information here is how many grid points are used in each direction of the unit cell.

There are methods for tasks such as allocating arrays, performing symmetry operations and integrating functions over space.

This is how a 2x2x2 3D array arr[x,y,z] is stored in memory:

3-----7
|\    |
| \   |
|  1-----5      z
2--|--6  |   y  |
 \ |   \ |    \ |
  \|    \|     \|
   0-----4      +-----x

iter_ixyz_r()

Iterator returning (ixyz, rr) where ixyz gives the index of the point and r is the point on the grid.

rpoint(ix, iy, iz)

The vector corresponding to the (ix, iy, iz) indices

to_string(verbose=0)

String representation.

Return type:

str

property nx: int

Number of points along x.

property ny: int

Number of points along y.

property nz: int

Number of points along z.

property inv_vectors

zeros(dtype=<class 'float'>, extra_dims=())

Returns new zeroed 3D array for this domain.

The type can be set with the dtype keyword. Extra dimensions can be added with extra_dims.

Return type:

ndarray

czeros(extra_dims=())

Returns new zeroed 3D complex array for this domain.

Return type:

ndarray

empty(dtype=<class 'float'>, extra_dims=())

Returns new uninitialized 3D numpy.ndarray for this domain.

The type can be set with the dtype keyword. Extra dimensions can be added with extra_dims.

cempty(extra_dims=())

Returns new uninitialized 3D complex numpy.ndarray for this domain.

Return type:

ndarray

random(dtype=<class 'float'>, extra_dims=())

Returns random real numpy.ndarray for this domain with val in [0.0, 1.0).

Return type:

ndarray

crandom(extra_dims=())

Returns random complex numpy.ndarray for this domain with val in [0.0, 1.0).

Return type:

ndarray

reshape(arr)

Reshape the array arr defined on the FFT box.

Returns numpy.ndarray with 4 dimensions (?, nx, ny, nz) where ?*nx*ny*nz == arr.size

Return type:

ndarray

fft_r2g(fr, shift_fg=False)

FFT of array fr given in real space.

Return type:

ndarray

fft_g2r(fg, fg_ishifted=False)

FFT of array fg given in G-space.

Return type:

ndarray

integrate(fr)

Integrate array(s) fr.

property gvecs: ndarray

Array with the reduced coordinates of the G-vectors.

Note

These are the G-vectors of the FFT box and should be used when we compute quantities on the FFT mesh. These vectors differ from the gvecs stored in abipy.core.gsphere.GSphere that are k-centered and enclosed by a sphere whose radius is defined by ecut.

property gmods: ndarray

[ng] numpy.ndarray with \(|G|\)

property rpoints: ndarray

numpy.ndarray with the points in real space in reduced coordinates.

i_closest_gridpoints(points)

Given a list of points, this function return a numpy.ndarray with the indices of the closest gridpoint.

Return type:

ndarray

dist_gridpoints_in_spheres(points, radius)

abipy.core.mixins module

Mixin classes

class abipy.core.mixins.AbinitNcFile(filepath)

Bases: BaseFile

Abstract class representing a Netcdf file with data saved according to the ETSF-IO specifications (when available). An AbinitNcFile has a netcdf reader to read data from file and build objects.

classmethod from_binary_string(bstring)

Build object from a binary string with the netcdf data. Useful for implementing GUIs in which widgets returns binary data.

Return type:

AbinitNcFile

ncdump(*nc_args, **nc_kwargs)

Returns a string with the output of ncdump.

Return type:

str

property abinit_version: str

three digits separated by comma.

Type:

String with the abinit version

abstract property params: dict

dictionary with the convergence parameters used to construct pandas.DataFrame.

get_dims_dataframe(as_dict=False, path='/')

Return type:

DataFrame

Return: pandas.DataFrame with the dimensions defined in the path group.

or dict if as_dict is True.

get_input_string()

Read and return input string stored in the netcdf. Only nc files generated by Abinit9 have this variable.

Return type:

str

get_ncfile_view(**kwargs)

Return panel Parameterized object with widgets to visualize netcdf dimensions and variables.

class abipy.core.mixins.Has_Structure

Bases: object

Mixin class for abipy.core.mixins.AbinitNcFile containing crystallographic data.

abstract property structure

Returns the abipy.core.structure.Structure object.

plot_bz(**kwargs)

Gives the plot (as a matplotlib object) of the symmetry line path in the Brillouin Zone.

Return type:

Any

show_bz(**kwargs)

Gives the plot (as a matplotlib object) of the symmetry line path in the Brillouin Zone.

Return type:

Any

export_structure(filepath)

Export the structure on file.

returns: abipy.iotools.visualizer.Visualizer instance.

visualize_structure_with(appname)

Visualize the crystalline structure with the specified visualizer.

See abipy.iotools.visualizer.Visualizer for the list of applications and formats supported.

yield_structure_figs(**kwargs)

Generates a predefined list of matplotlib figures with minimal input from the user.

yield_structure_plotly_figs(**kwargs)

Generates a predefined list of plotly figures with minimal input from the user.

class abipy.core.mixins.Has_ElectronBands

Bases: object

Mixin class for abipy.core.mixins.AbinitNcFile containing electron data.

abstract property ebands

Returns the abipy.electrons.ebands.ElectronBands object.

property nsppol: int

Number of spin polarizations

property nspinor: int

Number of spinors

property nspden: int

Number of indepedendent spin-density components.

property mband: int

Maximum number of bands.

property nband: int

Maximum number of bands.

property nelect: float

Number of electrons per unit cell

property nkpt: int

Number of k-points.

property kpoints

Iterable with the Kpoints.

property tsmear

get_ebands_params()

dictionary with the convergence parameters.

Return type:

dict

plot_ebands(**kwargs)

Plot the electron energy bands. See the ElectronBands.plot() for the signature.

Return type:

Any

plot_ebands_with_edos(edos, **kwargs)

Plot the electron energy bands with DOS. See the ElectronBands.plot_with_edos() for the signature.

Return type:

Any

get_edos(**kwargs)

Compute the electronic DOS on a linear mesh. Wraps ebands.get_edos.

yield_ebands_figs(**kwargs)

Generates a predefined list of matplotlib figures with minimal input from the user.

yield_ebands_plotly_figs(**kwargs)

Generates a predefined list of plotly figures with minimal input from the user.

expose_ebands(slide_mode=False, slide_timeout=None, expose_web=False, **kwargs)

Shows a predefined list of matplotlib figures for electron bands with minimal input from the user.

class abipy.core.mixins.Has_PhononBands

Bases: object

Mixin class for abipy.core.mixins.AbinitNcFile containing phonon data.

abstract property phbands

Returns the abipy.dfpt.phonons.PhononBands object.

get_phbands_params()

dictionary with the convergence parameters.

Return type:

dict

plot_phbands(**kwargs)

Plot the electron energy bands. See the PhononBands.plot() for the signature.””

Return type:

Any

yield_phbands_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

yield_phbands_plotly_figs(**kwargs)

This function generates a predefined list of plotly figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

expose_phbands(slide_mode=False, slide_timeout=None, **kwargs)

Show a predefined list of matplotlib figures for phonon bands with minimal input from the user.

class abipy.core.mixins.NotebookWriter

Bases: HasNotebookTools

Mixin class for objects that are able to generate jupyter notebooks. Subclasses must provide a concrete implementation of write_notebook.

abstractmethod write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporaty file is created. Return path to the notebook. A typical template:

# Preable.
nbformat, nbv, nb = self.get_nbformat_nbv_nb(title=None)

#####################
# Put your code here
nb.cells.extend([
    nbv.new_markdown_cell("# This is a markdown cell"),
    nbv.new_code_cell("a = 1"),
])
#####################

# Call _write_nb_nbpath
return self._write_nb_nbpath(nb, nbpath)

Return type:

str

classmethod pickle_load(filepath)

Loads the object from a pickle file.

pickle_dump(filepath=None)

Save the status of the object in pickle format. If filepath is None, a temporary file is created.

Return: The name of the pickle file.

Return type:

str

abstractmethod yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiopen.py or abiview.py to get a quick look at the results.

expose(slide_mode=False, slide_timeout=None, use_web=False, **kwargs)

Shows a predefined list of figures with minimal input from the user. Relies on the yield_fig methods implemented by the subclass to generate such figures.

Parameters:

use_web – True to show all figures inside a panel template executed in the local browser. False to show figures in different GUIs.

plotly_expose(**kwargs)

This function generates a predefined list of plotly figures with minimal input from the user. Relies on the yield_plotly_figs method implemented by the subclass in order to generate the figures.

class abipy.core.mixins.Has_Header

Bases: object

Mixin class for netcdf files containing the Abinit header.

property hdr

monty.collections.AttrDict with the Abinit header e.g. hdr.ecut.

class abipy.core.mixins.SlotPickleMixin

Bases: object

This mixin makes it possible to pickle/unpickle objects with __slots__

abipy.core.pauli module

Pauli matrices and operations associated to them.

class abipy.core.pauli.Pauli

Bases: object

Pauli matrices

project_mats(mats)

Project a batch of 2x2 Hermitian matrices onto the Pauli basis.

This method computes the coefficients of the given matrices in the Pauli basis (identity, sigma_x, sigma_y, sigma_z) for each 2x2 matrix in the input array. The input array must have shape […, 2, 2], where the trailing dimensions represent individual 2x2 matrices.

Parameters:

mats (np.ndarray) – An array of shape […, 2, 2], where each trailing 2x2 subarray is a matrix to be projected onto the Pauli basis.

Returns:

An array of shape […, 4], where the last dimension contains the coefficients (a_0, a_x, a_y, a_z) for the identity matrix, sigma_x, sigma_y, and sigma_z, respectively.

Return type:

np.ndarray

Examples

>>> import numpy as np
>>> mats = np.array([[[1, 0], [0, 1]], [[0, 1], [1, 0]]])  # Shape (2, 2, 2)
>>> result = project_mats(mats)
>>> print(result)  # Shape (2, 4)
[[ 0.5  0.   0.   0.5]
 [ 0.   0.5  0.   0. ]]

mats_from_projections(coefficients)

Reconstruct 2x2 matrices from their Pauli basis coefficients.

This method takes an array of coefficients (a_0, a_x, a_y, a_z) and reconstructs the corresponding 2x2 matrices using the Pauli basis (identity, sigma_x, sigma_y, sigma_z).

Parameters:

coefficients (np.ndarray) – An array of shape […, 4], where the last dimension contains the coefficients (a_0, a_x, a_y, a_z) for the identity matrix, sigma_x, sigma_y, and sigma_z, respectively.

Returns:

An array of shape […, 2, 2], where each trailing 2x2 matrix is reconstructed from the input coefficients.

Return type:

np.ndarray

Examples

>>> coefficients = np.array([[0.5, 0, 0, 0.5], [0, 0.5, 0, 0]])  # Shape (2, 4)
>>> result = reconstruct_mats(coefficients)
>>> print(result)  # Shape (2, 2, 2)
[[[1. 0.]
  [0. 1.]]
 [[0. 1.]
  [1. 0.]]]

abipy.core.perl module

abipy.core.release module

Release data for the AbiPy project.

abipy.core.restapi module

This module provides interfaces with the Materials Project REST API v2 to enable the creation of data structures and pymatgen objects using Materials Project data.

abipy.core.restapi.get_mprester()

Args:

class abipy.core.restapi.DatabaseStructures(structures, ids, data=None)

Bases: NotebookWriter

Store the results of a query to the MP database. This object is immutable, use add_entry to create a new instance.

filter_by_spgnum(spgnum)

Filter structures by space group number. Return new MpStructures object.

Return type:

MpStructures

add_entry(structure, entry_id, data_dict=None)

Add new entry, return new object.

Parameters:

• structure – New structure object.

• entry_id – ID associated to new structure.

• data_dict – Option dictionary with metadata.

property lattice_dataframe: DataFrame

pandas DataFrame with lattice parameters.

property coords_dataframe: DataFrame

pandas DataFrame with atomic positions.

property structure_dataframes

Pandas dataframes constructed from self.structures.

print_results(fmt='abivars', verbose=0, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Print pandas dataframe, structures using format fmt, and data to file file. fmt is automaticall set to cif if structure is disordered. Set fmt to None or empty string to disable structure output.

Return type:

None

yield_figs(**kwargs)

NOP required by NotebookWriter protocol.

write_notebook(nbpath=None, title=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

Return type:

str

class abipy.core.restapi.MpStructures(structures, ids, data=None)

Bases: DatabaseStructures

Store the results of a query to the Materials Project database.

dbname = 'Materials Project'

property dataframe: DataFrame

Pandas dataframe constructed from self.data. None if data is not available.

open_browser(browser=None, limit=10)

Parameters:

• browser – Open webpage in browser. Use default if $BROWSER if None.

• limit – Max number of tabs opened in browser. None for no limit.

class abipy.core.restapi.CodStructures(structures, ids, data=None)

Bases: DatabaseStructures

Store the results of a query to the COD database [Grazulis2011].

dbname = 'COD'

property dataframe: DataFrame

pandas.DataFrame constructed. Essentially geometrical info and space groups found by spglib as COD API is rather limited.

class abipy.core.restapi.Dotdict

Bases: dict

dotget(key, default=None)

d.dotget[“foo.bar”] –> d[“foo”][“bar”] if “foo.bar” not in self

abipy.core.site_symmetries module

This module provides objects related to site symmetries

class abipy.core.site_symmetries.SiteSymmetries(structure)

Bases: Has_Structure

property structure: Structure

abipy.core.structure.Structure object.

to_string(verbose=0)

String representation with verbosity level verbose.

Return type:

str

get_wyckoff_dataframe(view='all', select_symbols=None, decimals=5, verbose=0)

Find Wyckoff positions.

Parameters:

• view

• select_symbols

• decimals – Number of decimal places to round to. If decimals is negative, it specifies the number of positions to the left of the decimal point.

• verbose – Verbosity level.

Return type:

DataFrame

Return pandas.DataFrame with cartesian tensor components as columns and (inequivalent) sites along the rows.

get_tensor_rank2_dataframe(view='all', select_symbols=None, decimals=5, verbose=0)

Use site symmetries to detect independent elements of rank 2 tensor.

Parameters:

• view

• select_symbols

• decimals – Number of decimal places to round to. If decimals is negative, it specifies the number of positions to the left of the decimal point.

• verbose – Verbosity level

Return type:

DataFrame

Return pandas.DataFrame with cartesian tensor components as columns and (inequivalent) sites along the rows.

check_site_symmetries(tcart, verbose=0)

Test whether a set of tensors associated to the crystalline sites are compatible with the space group symmetries.

Parameters:

• tcart – (natom, 3, 3) array

• verbose – Verbosity level.

Return type:

float

Return: max_err

abipy.core.skw module

Shankland-Koelling-Wood Fourier interpolation scheme. For the theoretical background see [Euwema1969, Koelling1986, Madsen2006, Pickett1988].

class abipy.core.skw.ElectronInterpolator

Bases: object

Abstract class for band structure interpolator.

symprec = 1e-05

angle_tolerance = -1.0

occtype = 'insulator'

use_cache = True

classmethod pickle_load(filepath)

Loads the object from a pickle file.

pickle_dump(filepath)

Save the status of the object in pickle format.

Return type:

None

get_sampling(mesh, is_shift)

Use spglib to compute the k-points in the IBZ with the corresponding weights as well as the k-points in the full BZ.

Parameters:

• mesh

• is_shift

Return: named tuple with the following attributes:

ibz: nibz weights: bz: nbz grid:

property val_ib: int

The index of the valence band.

get_edos(kmesh, is_shift=None, method='gaussian', step=0.1, width=0.2, wmesh=None)

Compute the electron DOS on a linear mesh.

Parameters:

• kmesh – Three integers with the number of divisions along the reciprocal primitive axes.

• is_shift – three integers (spglib API). When is_shift is not None, the kmesh is shifted along the axis in half of adjacent mesh points irrespective of the mesh numbers. None means unshited mesh.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• mesh – Frequency mesh to use. If None, the mesh is computed automatically from the eigenvalues.

Returns:

(mesh, values, integral)

plot_dos_vs_kmeshes(kmeshes, is_shift=None, method='gaussian', step=0.1, width=0.2, fontsize=12, ax=None, **kwargs)

Plot (interpolated) DOSes computed with different meshes.

Parameters:

• kmeshes – List of kmeshes. Each item is given by three integers with the number of divisions along the reciprocal primitive axes.

• is_shift – three integers (spglib API). When is_shift is not None, the kmesh is shifted along the axis in half of adjacent mesh points irrespective of the mesh numbers. None means unshited mesh.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – Legend and title fontsize.

Return type:

Any

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot. Default: None.
show	True to show the figure. Default: True.
savefig	“abc.png” or “abc.svg” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4).
tight_layout	True to call fig.tight_layout. Default: False.
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly: Default: False

abstractmethod eval_sk(spin, kpt, der1=None, der2=None)

Interpolate eigenvalues for all bands at a given (spin, k-point). Optionally compute gradients and Hessian matrices.

Parameters:

• spin – Spin index.

• kpt – K-point in reduced coordinates.

• der1 – If not None, output gradient is stored in der1[nband, 3].

• der2 – If not None, output Hessian is der2[nband, 3, 3].

Returns:

oeigs[nband]

interp_kpts(kfrac_coords, dk1=False, dk2=False)

Interpolate energies on an arbitrary set of k-points. Optionally, compute gradients and Hessian matrices.

Parameters:

• kfrac_coords – k-points in reduced coordinates.

• dk1 (bool) – True if gradient is wanted.

• dk2 (bool) – True to compute 2nd order derivatives.

Returns:

interpolated energies in eigens[nsppol, len(kfrac_coords), nband] gradient in dedk[self.nsppol, len(kfrac_coords), self.nband, 3)) hessian in dedk2[self.nsppol, len(kfrac_coords), self.nband, 3, 3)) gradient and hessian are set to None if not computed.

Return type:

namedtuple with

interp_kpts_and_enforce_degs(kfrac_coords, ref_eigens, atol=0.0001)

Interpolate energies on an arbitrary set of k-points. Use ref_eigens to detect degeneracies and average the interpolated values in the degenerate subspace.

class abipy.core.skw.SkwInterpolator(lpratio, kpts, eigens, fermie, nelect, cell, symrel, has_timrev, filter_params=None, verbose=1)

Bases: ElectronInterpolator

This object implements the Shankland-Koelling-Wood Fourier interpolation scheme. It can be used to interpolate functions in k-space with the periodicity of the reciprocal lattice and satisfying F(k) = F(Sk) for each rotation S belonging to the point group of the crystal. For readability reason, the names of the variables are chosen assuming we are interpolating electronic eigenvalues but the same object can be used to interpolate other quantities. Just set the first dimension to 1.

to_string(verbose=0)

String representation.

Return type:

str

eval_sk(spin, kpt, der1=None, der2=None)

Interpolate eigenvalues for all bands at a given (spin, k-point). Optionally compute gradients and Hessian matrices.

Parameters:

• spin – Spin index.

• kpt – K-point in reduced coordinates.

• der1 – If not None, output gradient is stored in der1[nband, 3].

• der2 – If not None, output Hessian is der2[nband, 3, 3].

Return type:

ndarray

Returns:

oeigs[nband]

get_stark(kpt)

Return the star function for k-point kpt.

Parameters:

kpt – K-point in reduced coordinates.

Return type:

ndarray

Returns:

complex array of shape [self.nr]

get_stark_dk1(kpt)

Compute the 1st-order derivative of the star function wrt k

Parameters:

kpt – K-point in reduced coordinates.

Return type:

ndarray

Returns:

complex array [3, self.nr] with the derivative of the star function wrt k in reduced coordinates.

get_stark_dk2(kpt)

Compute the 2nd-order derivatives of the star function wrt k.

Parameters:

kpt – K-point in reduced coordinates.

Return type:

ndarray

Returns:

Complex numpy array of shape [3, 3, self.nr] with the 2nd-order derivatives of the star function wrt k in reduced coordinates.

abipy.core.skw.extract_point_group(symrel, has_timrev)

Extract the point group rotations from the spacegroup. Add time-reversal if spatial inversion is not present and has_timrev.

Return type:

tuple

Returns:

(ptg_symrel, ptg_symrec) with rotations in real- and reciprocal-space.

abipy.core.structure module

This module defines basic objects representing the crystalline structure.

abipy.core.structure.mp_match_structure(obj)

Finds matching structures on the Materials Project database.

Parameters:

obj – filename or abipy.core.structure.Structure object.

Returns:

MpStructures object with

structures: List of matching structures and list of Materials Project identifier.

abipy.core.structure.mp_search(chemsys_formula_id)

Connect to the materials project database. Get a list of structures corresponding to a chemical system, formula, or materials_id.

Parameters:

chemsys_formula_id (str) – A chemical system (e.g., Li-Fe-O), or formula (e.g., Fe2O3) or materials_id (e.g., mp-1234).

Returns:

MpStructures object with

List of Structure objects, Materials project ids associated to structures. and List of dictionaries with MP data (same order as structures).

Note that the attributes evaluate to False if no match is found.

abipy.core.structure.cod_search(formula, primitive=False)

Connect to the COD database. Get list of structures corresponding to a chemical formula

Parameters:

• formula (str) – Chemical formula (e.g., Fe2O3)

• primitive (bool) – True if primitive structures are wanted. Note that many COD structures are not primitive.

Returns:

CodStructures object with

List of Structure objects, COD ids associated to structures. and List of dictionaries with COD data (same order as structures).

Note that the attributes evaluate to False if no match is found

class abipy.core.structure.Structure(lattice, species, coords, charge=None, validate_proximity=False, to_unit_cell=False, coords_are_cartesian=False, site_properties=None, labels=None, properties=None)

Bases: Structure, NotebookWriter

Extends pymatgen.core.structure.Structure with Abinit-specific methods.

Inheritance Diagram

classmethod as_structure(obj)

Convert obj into a abipy.core.structure.Structure. Accepts:

• Structure object.

• Filename

• Dictionaries (JSON format or dictionaries with abinit variables).

• Objects with a structure attribute.

• ASE atoms.

Return type:

Structure

classmethod from_file(filepath, primitive=False, sort=False)

Reads a structure from a file. For example, anything ending in a “cif” is assumed to be a Crystallographic Information Format file. Supported formats include CIF, POSCAR/CONTCAR, CHGCAR, LOCPOT, vasprun.xml, CSSR, Netcdf and pymatgen’s JSON serialized structures.

Netcdf files supported:

All files produced by ABINIT with info of the crystalline geometry HIST.nc, in this case the last structure of the history is returned.

Parameters:

• filename (str) – The filename to read from.

• primitive (bool) – Whether to convert to a primitive cell Only available for cifs, POSCAR, CSSR, JSON, YAML Defaults to True.

• sort (bool) – Whether to sort sites. Default to False.

Return type:

Structure

Returns: abipy.core.structure.Structure object

classmethod from_mpid(material_id)

Get a Structure corresponding to a material_id.

Parameters:

• material_id (str) – Materials Project material_id (a string, e.g., mp-1234).

• final (bool) – Whether to get the final structure, or the initial (pre-relaxation) structure. Defaults to True.

Return type:

Structure

Returns: abipy.core.structure.Structure object.

classmethod from_cod_id(cod_id, primitive=False, **kwargs)

Queries the COD database for a structure by id. Returns abipy.core.structure.Structure object.

Parameters:

• cod_id (int) – COD id.

• primitive (bool) – True if primitive structures are wanted. Note that many COD structures are not primitive.

• kwargs – Arguments passed to get_structure_by_id

Return type:

Structure

Returns: abipy.core.structure.Structure object.

classmethod from_phonopy_atoms(atoms)

Returns structure from phonopy Atoms.

Return type:

Structure

classmethod from_ase_atoms(atoms)

Returns structure from ASE Atoms.

Parameters:

atoms – ASE Atoms object

Return type:

Structure

property n_elems: int

Number of types of atoms.

to_ase_atoms(calc=None)

Returns ASE Atoms object from structure and attach calculator calc.

get_phonopy_atoms()

Convert a pymatgen Structure object to a PhonopyAtoms object.

classmethod boxed_molecule(pseudos, cart_coords, acell=(10, 10, 10))

Creates a molecule in a periodic box of lengths acell in Bohr.

Parameters:

• pseudos – List of pseudopotentials

• cart_coords – Cartesian coordinates

• acell – Lengths of the box in Bohr

Return type:

Structure

classmethod boxed_atom(pseudo, cart_coords=(0, 0, 0), acell=(10, 10, 10))

Creates an atom in a periodic box of lengths acell in Bohr.

Parameters:

• pseudo – Pseudopotential object.

• cart_coords – Cartesian coordinates in Angstrom

• acell – Lengths of the box in Bohr (Abinit input variable)

Return type:

Structure

classmethod bcc(a, species, primitive=True, units='ang', **kwargs)

Build a primitive or a conventional bcc crystal structure.

Parameters:

• a – Lattice parameter (Angstrom if units is not given)

• species – Chemical species. See __init__ method of pymatgen.core.structure.Structure

• primitive – if True a primitive cell will be produced, otherwise a conventional one

• units – Units of input lattice parameters e.g. “bohr”, “pm”

• kwargs – All keyword arguments accepted by pymatgen.core.structure.Structure.

Return type:

Structure

classmethod fcc(a, species, primitive=True, units='ang', **kwargs)

Build a primitive or a conventional fcc crystal structure.

Parameters:

• a (float) – Lattice parameter (Angstrom if units is not given)

• species – Chemical species. See __init__ method of pymatgen.Structure

• primitive – if True a primitive cell will be produced, otherwise a conventional one

• units – Units of input lattice parameters e.g. “bohr”, “pm”

• kwargs – All keyword arguments accepted by pymatgen.Structure

Return type:

Structure

classmethod zincblende(a, species, units='ang', **kwargs)

Build a primitive zincblende crystal structure.

Parameters:

• a – Lattice parameter (Angstrom if units is not given)

• species – Chemical species. See __init__ method of pymatgen.Structure

• units – Units of input lattice parameters e.g. “bohr”, “pm”

• kwargs – All keyword arguments accepted by pymatgen.Structure

Return type:

Structure

structure = Structure.zincblende(a, ["Zn", "S"])

classmethod rocksalt(a, species, units='ang', **kwargs)

Build a primitive fcc crystal structure.

Parameters:

• a – Lattice parameter (Angstrom if units is not given)

• units – Units of input lattice parameters e.g. “bohr”, “pm”

• species – Chemical species. See __init__ method of pymatgen.Structure

• kwargs – All keyword arguments accepted by pymatgen.Structure

Return type:

Structure

structure = Structure.rocksalt(a, ["Na", "Cl"])

classmethod ABO3(a, species, units='ang', **kwargs)

Peroviskite structures.

Parameters:

• a – Lattice parameter (Angstrom if units is not given)

• species – Chemical species. See __init__ method of pymatgen.Structure

• units – Units of input lattice parameters e.g. “bohr”, “pm”

• kwargs – All keyword arguments accepted by pymatgen.Structure

Return type:

Structure

classmethod from_abistring(string)

Initialize Structure from a string with Abinit input variables.

Return type:

Structure

classmethod from_abivars(*args, **kwargs)

Build a abipy.core.structure.Structure object from a dictionary with ABINIT variables.

al_structure = Structure.from_abivars(
    acell=3*[7.5],
    rprim=[0.0, 0.5, 0.5,
           0.5, 0.0, 0.5,
           0.5, 0.5, 0.0],
    typat=1,
    xred=[0.0, 0.0, 0.0],
    ntypat=1,
    znucl=13,
)

xred can be replaced with xcart or xangst.

Return type:

Structure

property species_by_znucl

Return list of unique species found in the structure ordered according to sites.

Example

Site0: 0.5 0 0 O Site1: 0 0 0 Si

produces [Specie_O, Specie_Si] and not set([Specie_O, Specie_Si]) as in types_of_specie.

Important:: We call this method species_by_znucl but this does not mean that the list can automagically reproduce the value of znucl(ntypat) specified in an arbitrary ABINIT input file created by the user. This array is ordered as the znucl list produced by AbiPy when writing the structure to the input file.

to_string(title=None, verbose=0)

String representation. Extends the implementation of the superclass.

Return type:

str

to(fmt=None, filename=None, **kwargs)

Output the structure to a string (and to a file when filename is given).

Parameters:

• filename (PathLike) – If provided, output will be written to a file. If fmt is not specified, the format is determined from the filename. Defaults is None, i.e. string output.

• fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If specified, it overrides whatever the filename is. Options include “cif”, “poscar”, “cssr”, “json”, “xsf”, “mcsqs”, “prismatic”, “yaml”, “yml”, “fleur-inpgen”, “pwmat”, “aims”. Case insensitive.

• **kwargs – Kwargs pass thru to relevant methods. This allows the passing of parameters like symprec to the CifWriter.__init__ method for generation of symmetric CIFs.

Returns:

String representation of structure in given format. If a filename

is provided, the same string is written to the file.

Return type:

str

compare(other, atol=1e-06)

Compare two structures with absolute tolerance atol. Return: bool indicating if structures are equal and string with error message, if any.

Return type:

tuple[bool, str]

mp_match(**kwargs)

Finds matching structures on the Materials Project database. Just a wrapper around mp_match_structure.

write_cif_with_spglib_symms(filename, symprec=0.001, angle_tolerance=5.0, significant_figures=8, ret_string=False)

Write CIF file with symmetries as detected by spglib.

Parameters:

• symprec (float) – If not none, finds the symmetry of the structure and writes the cif with symmetry information. Passes symprec to the SpacegroupAnalyzer.

• significant_figures (int) – Specifies precision for formatting of floats. Defaults to 8.

• angle_tolerance (float) – Angle tolerance for symmetry finding. Passes angle_tolerance to the SpacegroupAnalyzer. Used only if symprec is not None.

• ret_string – True to return string.

to_abivars(enforce_znucl=None, enforce_typat=None, **kwargs)

Returns a dictionary with the ABINIT variables.

Parameters:

• znucl. (enforce_znucl[ntypat] = Enforce this value for)

• 1. (enforce_typat[natom] = Fortran conventions. Start to count from)

Return type:

dict

property latex_formula: str

e.g., Fe2O3 is transformed to Fe$_{2}$O$_{3}$.

Type:

LaTeX formatted formula

property poscar_string: str

String with the structure in POSCAR format.

property abi_string: str

String with the ABINIT input associated to this structure.

get_abi_string(fmt='abinit_input')

Return a string with the ABINIT input associated to this structure. Two formats are available. fmt=”abinit_input” corresponds to the standard format with typat, znucl. fmt=”abicell” is the lightweight format that uses xred_symbols This format can be used to include the structure in the input via the structure “abivars:FILE” syntax.

Return type:

str

get_panel(with_inputs=True, **kwargs)

Build panel with widgets to interact with the structure either in a notebook or in a bokeh app.

Parameters:

with_inputs – True if tabs for generating input files should be shown.

get_conventional_standard_structure(international_monoclinic=True, symprec=0.001, angle_tolerance=5)

Gives a structure with a conventional cell according to certain standards. The standards are defined in [Setyawan2010] They basically enforce as much as possible norm(a1) < norm(a2) < norm(a3)

Returns: The structure in a conventional standardized cell

Return type:

Structure

abi_primitive(symprec=0.001, angle_tolerance=5, no_idealize=0)

Return type:

Structure

new_with_uptri_lattice(mode='uptri')

Build and return new structure with cell matrix in upper triangle form. In the cell matrix, lattice vectors are along rows.

Parameters:

wanted. (mode="lowtri" if lower triangle cell matrix is)

Return type:

Structure

refine(symprec=0.001, angle_tolerance=5)

Get the refined structure based on detected symmetry. The refined structure is a conventional cell setting with atoms moved to the expected symmetry positions.

Returns: Refined structure.

Return type:

Structure

abi_sanitize(symprec=0.001, angle_tolerance=5, primitive=True, primitive_standard=False, atol=1e-12)

Returns a new structure in which:

• Structure is refined.

• Reduced to primitive settings.

• Lattice vectors are exchanged if the triple product is negative

Parameters:

• symprec (float) – Symmetry precision used to refine the structure.

• angle_tolerance (float) – Tolerance on angles. if symprec is None and angle_tolerance is None, no structure refinement is performed.

• primitive (bool) – Returns most primitive structure found.

• primitive_standard (bool) – Whether to convert to a primitive cell using the standards defined in Setyawan, W., & Curtarolo, S. (2010). High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299-312. doi:10.1016/j.commatsci.2010.05.010

• atol – Components whose absolute value are less than atol are set to zero. Use None or zero to disable this step.

Return type:

Structure

get_oxi_state_decorated(**kwargs)

Use pymatgen.analysis.bond_valence.BVAnalyzer to estimate oxidation states Return oxidation state decorated structure. This currently works only for ordered structures only.

Parameters:

kwargs – Arguments passed to BVAnalyzer

Return type:

Structure

Returns:

A modified structure that is oxidation state decorated.

property reciprocal_lattice

Reciprocal lattice of the structure. Note that this is the standard reciprocal lattice used for solid state physics with a factor of 2 * pi i.e. a_j . b_j = 2pi delta_ij

If you are looking for the crystallographic reciprocal lattice, use the reciprocal_lattice_crystallographic property.

spget_lattice_type(symprec=0.001, angle_tolerance=5)

Call spglib to get the lattice for the structure, e.g., (triclinic, orthorhombic, cubic, etc.). This is the same than the crystal system with the exception of the hexagonal/rhombohedral lattice

Parameters:

• symprec (float) – Symmetry precision for distance

• angle_tolerance (float) – Tolerance on angles.

Returns:

Lattice type for structure or None if type cannot be detected.

Return type:

(str)

spget_equivalent_atoms(symprec=0.001, angle_tolerance=5, printout=False)

Call spglib to find the inequivalent atoms and build symmetry tables.

Parameters:

• symprec (float) – Symmetry precision for distance.

• angle_tolerance (float) – Tolerance on angles.

• printout (bool) – True to print symmetry tables.

Returns:

namedtuple (irred_pos, eqmap, spgdata) with the following attributes:

* irred_pos: array giving the position of the i-th irred atom in the structure.
    The number of irred atoms is len(irred_pos).
*   eqmap: Mapping irred atom position --> list with positions of symmetrical atoms.
*   wyckoffs: Wyckoff letters.
*   wyck_mult: Array with Wyckoff multiplicity.
*   wyck_labels: List of labels with Wyckoff multiplicity and letter e.g. 3a
*   site_labels: Labels for each site in computed from element symbol and wyckoff positions e.g Si2a
*   spgdata: spglib dataset with additional data reported by spglib_.

Example:

for irr_pos in irred_pos:

eqmap[irr_pos] # List of symmetrical positions associated to the irr_pos atom.

spget_summary(symprec=0.001, angle_tolerance=5, site_symmetry=False, verbose=0)

Return string with full information about crystalline structure i.e. space group, point group, wyckoff positions, equivalent sites.

Parameters:

• symprec (float) – Symmetry precision for distance.

• angle_tolerance (float) – Tolerance on angles.

• site_symmetry – True to show site symmetries i.e. the point group operations that leave the site invariant.

• verbose (int) – Verbosity level.

Return type:

str

property abi_spacegroup

AbinitSpaceGroup instance with Abinit symmetries read from the netcd file. None if abinit symmetries are not available e.g. if the structure has been created from a CIF file.

set_abi_spacegroup(spacegroup)

AbinitSpaceGroup setter.

Return type:

None

property has_abi_spacegroup: bool

True is the structure contains info on the spacegroup.

spgset_abi_spacegroup(has_timerev, overwrite=False)

Call spglib to find the spacegroup of the crystal, create new AbinitSpaceGroup object and store it in self.abi_spacegroup.

Parameters:

• has_timerev (bool) – True if time-reversal can be used.

• overwrite (bool) – By default, the method raises ValueError if the object already has the list of symmetries found by Abinit.

Returns: AbinitSpaceGroup

property indsym

Compute indsym (natom, nsym, 4) array.

For each isym, iatom, the fourth element is label of atom into which iatom is sent by INVERSE of symmetry operation isym; first three elements are the primitive translations which must be subtracted after the transformation to get back to the original unit cell (see symatm.F90).

property site_symmetries

Object with SiteSymmetries.

spget_site_symmetries()

abiget_spginfo(tolsym=None, pre=None)

Call Abinit to get spacegroup information. Return dictionary with e.g. {‘bravais’: ‘Bravais cF (face-center cubic)’, ‘spg_number’: 227, ‘spg_symbol’: ‘Fd-3m’}.

Parameters:

• tolsym – Abinit tolsym input variable. None corresponds to the default value.

• pre – Keywords in dictionary are prepended with this string

Return type:

dict

print_neighbors(radius=2.0)

Get neighbors for each atom in the unit cell, out to a distance radius in Angstrom Print results.

Return type:

None

property has_zero_dynamical_quadrupoles

Dynamical quadrupoles are nonzero in all noncentrosymmetric crystals, but also in centrosymmetric ones if one or more atoms are placed at noncentrosymmetric sites.

property hsym_kpath

Returns an instance of pymatgen.symmetry.bandstructure.HighSymmKpath. (Database of high symmetry k-points and high symmetry lines).

property hsym_kpoints

abipy.core.kpoints.KpointList object with the high-symmetry K-points.

get_kcoords_from_names(knames, cart_coords=False)

Return numpy array with the fractional coordinates of the high-symmetry k-points listed in knames.

Parameters:

• knames – List of strings with the k-point labels.

• cart_coords – True if the coords dataframe should contain Cartesian coordinates instead of Reduced coordinates.

Return type:

ndarray

property hsym_stars: list

List of abipy.core.kpoints.KpointStar objects. Each star is associated to one of the special k-points present in the pymatgen database.

get_sorted_structure_z()

Order the structure according to increasing Z of the elements

Return type:

Structure

findname_in_hsym_stars(kpoint)

Returns the name of the special k-point, None if kpoint is unknown.

Return type:

str | None

get_symbol2indices()

Return a dictionary mapping chemical symbols to numpy array with the position of the atoms.

Return type:

dict

Example

MgB2 –> {Mg: [0], B: [1, 2]}

get_symbol2coords()

Return a dictionary mapping chemical symbols to a [ntype_symbol, 3] numpy array with the fractional coordinates.

Return type:

dict

dot(coords_a, coords_b, space='r', frac_coords=False)

Compute the scalar product of vector(s) either in real space or reciprocal space.

Parameters:

• coords (3x1 array) – Array-like object with the coordinates.

• space (str) – “r” for real space, “g” for reciprocal space.

• frac_coords (bool) – Whether the vector corresponds to fractional or cartesian coordinates.

Returns:

one-dimensional numpy array.

norm(coords, space='r', frac_coords=True)

Compute the norm of vector(s) either in real space or reciprocal space.

Parameters:

• coords (3x1 array) – Array-like object with the coordinates.

• space (str) – “r” for real space, “g” for reciprocal space.

• frac_coords (bool) – Whether the vector corresponds to fractional or cartesian coordinates.

Returns:

one-dimensional numpy array.

scale_lattice(new_volume)

Return a new abipy.core.structure.Structure with volume new_volume by performing a scaling of the lattice vectors so that length proportions and angles are preserved.

Return type:

Structure

magnetic_supercell(scaling_matrix, magmom=None)

Make a supercell. Allow sites outside the unit cell.

Parameters:

scaling_matrix (int | Sequence[int]) –

A scaling matrix for transforming the lattice vectors. Has to be all integers. Several options are possible:

1. A sequence of three scaling factors. e.g. [2, 1, 1] specifies that the supercell should have dimensions 2a x b x c.

2. A number, which simply scales all lattice vectors by the same factor.

Return type:

Structure

Returns:

Supercell structure. Note that a Structure is always returned, even if the input structure is a subclass of Structure. This is to avoid different arguments signatures from causing problems. If you prefer a subclass to return its own type, you need to override this method in the subclass.

get_dict4pandas(symprec=0.01, angle_tolerance=5.0, with_spglib=True)

Return a dict with the most important structural parameters useful to construct pandas DataFrames.

• Chemical formula and number of atoms.

• Lattice lengths, angles and volume.

• The spacegroup number computed by Abinit (set to None if not available).

• The spacegroup number and symbol computed by spglib (if with_spglib).

Parameters:

• with_spglib (bool) – If True, spglib is invoked to get the spacegroup symbol and number

• symprec (float) – Symmetry precision used to refine the structure.

• angle_tolerance (float) – Tolerance on angles.

Return type:

dict

get_symb2coords_dataframe(with_cart_coords=False)

Return dictionary mapping element symbol to DataFrame with atomic positions in cartesian coordinates.

Parameters:

with_cart_coords – True if Cartesian coordinates should be added as well.

Return type:

dict

plot(**kwargs)

Plot structure in 3D with matplotlib. Return matplotlib Figure. See plot_structure for kwargs.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot. Default: None.
show	True to show the figure. Default: True.
savefig	“abc.png” or “abc.svg” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4).
tight_layout	True to call fig.tight_layout. Default: False.
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly: Default: False

plotly(**kwargs)

Plot structure in 3D with plotly. Return plotly Figure. See plot_structure for kwargs

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
hovermode	True to show the hover info (default: False)
savefig	“abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file.
write_json	Write plotly figure to write_json JSON file. Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor
renderer	(str or None (default None)) – A string containing the names of one or more registered renderers (separated by “+” characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See <https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html>
config (dict)	A dict of parameters to configure the figure. The defaults are set in plotly.js.
chart_studio	True to push figure to chart_studio server. Requires authentication. Default: False.
template	Plotly template. See <https://plotly.com/python/templates> [“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”, “seaborn”, “simple_white”, “none”] Default is None that is the default template is used.

plot_bz(ax=None, pmg_path=True, with_labels=True, **kwargs)

Use matplotlib to plot the symmetry line path in the Brillouin Zone.

Parameters:

• ax – matplotlib Axes or None if a new figure should be created.

• pmg_path (bool) – True if the default path used in pymatgen should be show.

• with_labels (bool) – True to plot k-point labels.

Returns: matplotlib.figure.Figure.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot. Default: None.
show	True to show the figure. Default: True.
savefig	“abc.png” or “abc.svg” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4).
tight_layout	True to call fig.tight_layout. Default: False.
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly: Default: False

plotly_bz(fig=None, pmg_path=True, with_labels=True, **kwargs)

Use plotly to plot the symmetry line path in the Brillouin Zone.

Parameters:

• fig – plotly figure or None if a new figure should be created.

• pmg_path (bool) – True if the default path used in pymatgen should be show.

• with_labels (bool) – True to plot k-point labels.

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
hovermode	True to show the hover info (default: False)
savefig	“abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file.
write_json	Write plotly figure to write_json JSON file. Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor
renderer	(str or None (default None)) – A string containing the names of one or more registered renderers (separated by “+” characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See <https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html>
config (dict)	A dict of parameters to configure the figure. The defaults are set in plotly.js.
chart_studio	True to push figure to chart_studio server. Requires authentication. Default: False.
template	Plotly template. See <https://plotly.com/python/templates> [“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”, “seaborn”, “simple_white”, “none”] Default is None that is the default template is used.

plot_xrd(wavelength='CuKa', symprec=0, debye_waller_factors=None, two_theta_range=(0, 90), annotate_peaks=True, ax=None, **kwargs)

Use pymatgen XRDCalculator to show the XRD plot.

Parameters:

• wavelength (str/float) – The wavelength can be specified as either a float or a string. If it is a string, it must be one of the supported definitions in the AVAILABLE_RADIATION class variable, which provides useful commonly used wavelengths. If it is a float, it is interpreted as a wavelength in angstroms. Defaults to “CuKa”, i.e, Cu K_alpha radiation.

• symprec (float) – Symmetry precision for structure refinement. If set to 0, no refinement is done. Otherwise, refinement is performed using spglib with provided precision.

• symbol (debye_waller_factors ({element) – float}): Allows the specification of Debye-Waller factors. Note that these factors are temperature dependent.

• two_theta_range ([float of length 2]) – Tuple for range of two_thetas to calculate in degrees. Defaults to (0, 90). Set to None if you want all diffracted beams within the limiting sphere of radius 2 / wavelength.

• annotate_peaks (bool) – Whether to annotate the peaks with plane information.

• ax – matplotlib Axes or None if a new figure should be created.

Return type:

Any

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot. Default: None.
show	True to show the figure. Default: True.
savefig	“abc.png” or “abc.svg” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4).
tight_layout	True to call fig.tight_layout. Default: False.
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly: Default: False

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

export(filename, visu=None, verbose=1)

Export the crystalline structure to file filename.

Parameters:

• filename (str) – String specifying the file path and the file format. The format is defined by the file extension. filename=”prefix.xsf”, for example, will produce a file in XSF format. An empty prefix, e.g. “.xsf” makes the code use a temporary file.

• visu – abipy.iotools.visualizer.Visualizer subclass. By default, this method returns the first available visualizer that supports the given file format. If visu is not None, an instance of visu is returned. See abipy.iotools.visualizer.Visualizer for the list of applications and formats supported.

• verbose – Verbosity level

Returns: Visualizer instance.

get_chemview(**kwargs)

Visualize structure inside the jupyter notebook using chemview package.

plot_vtk(show=True, **kwargs)

Visualize structure with VTK. Requires vVTK python bindings.

Parameters:

• show – True to show structure immediately.

• kwargs – keyword arguments passed to StructureVis.

Return: StructureVis object.

plot_mayaview(figure=None, show=True, **kwargs)

Visualize structure with mayavi.

plot_atoms(rotations='default', **kwargs)

Plot 2d representation with matplotlib using ASE plot_atoms function.

Parameters:

• rotations – String or List of strings. Each string defines a rotation (in degrees) in the form ‘10x,20y,30z’ Note that the order of rotation matters, i.e. ‘50x,40z’ is different from ‘40z,50x’.

• kwargs – extra kwargs passed to plot_atoms ASE function.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot. Default: None.
show	True to show the figure. Default: True.
savefig	“abc.png” or “abc.svg” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4).
tight_layout	True to call fig.tight_layout. Default: False.
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly: Default: False

get_ngl_view()

Visualize the structure with nglview inside the jupyter notebook.

get_crystaltk_view()

Visualize the structure with crystal_toolkit inside the jupyter notebook.

get_jsmol_view(symprec=None, verbose=0, **kwargs)

Visualize the structure with jsmol inside the jupyter notebook.

Parameters:

• symprec (float) – If not none, finds the symmetry of the structure and writes the CIF with symmetry information. Passes symprec to the spglib SpacegroupAnalyzer.

• verbose – Verbosity level.

visualize(appname='vesta')

Visualize the crystalline structure with visualizer. See abipy.iotools.visualizer.Visualizer for the list of applications and formats supported.

convert(fmt='cif', **kwargs)

Return string with the structure in the given format fmt Options include: “abivars”, “cif”, “xsf”, “poscar”, “siesta”, “wannier90”, “cssr”, “json”.

Return type:

str

displace(displ, eta, frac_coords=True, normalize=True)

Displace the sites of the structure along the displacement vector displ.

The displacement vector is first rescaled so that the maximum atomic displacement is one Angstrom, and then multiplied by eta. Hence passing eta=0.001, will move all the atoms so that the maximum atomic displacement is 0.001 Angstrom.

Parameters:

• displ – Displacement vector with 3*len(self) entries in fractional coordinates.

• eta – Scaling factor in Ang

• frac_coords – Boolean stating whether displ corresponds to fractional or cartesian coordinates.

displace_one_site(index, displ, eta, frac_coords=True, to_unit_cell=False)

Displace one site of the structure along the displacement vector displ.

The displacement vector is first rescaled so that the maximum atomic displacement is one Angstrom, and then multiplied by eta. Hence passing eta=0.001, will move the site so that the maximum atomic displacement is 0.001 Angstrom.

Parameters:

• index – Index of the site (starts at 0).

• displ – Displacement vector in fractional coordinates.

• eta – Scaling factor in Ang

• frac_coords (bool) – Boolean stating whether displ corresponds to fractional or cartesian coordinates.

• to_unit_cell (bool) – Whether new sites are transformed to unit cell

Return type:

Structure

get_smallest_supercell(qpoint, max_supercell)

Parameters:

• qpoint – q vector in reduced coordinates in reciprocal space.

• max_supercell – vector with the maximum supercell size

Returns: the scaling matrix of the supercell

make_doped_supercells(scaling_matrix, replaced_atom, dopant_atom)

Returns a list of doped supercell structures, one for each non-equivalent site of the replaced atom.

Parameters:

• scaling_matrix – A scaling matrix for transforming the lattice vectors. Has to be all integers. Several options are possible: a) A full 3x3 scaling matrix defining the linear combination of the old lattice vectors. E.g., [[2,1,0],[0,3,0],[0,0,1]] generates a new structure with lattice vectors a_new = 2a + b, b_new = 3b, c_new = c where a, b, and c are the lattice vectors of the original structure. b) A sequence of three scaling factors. e.g., [2, 1, 1] specifies that the supercell should have dimensions 2a x b x c. c) A number, which simply scales all lattice vectors by the same factor.

• atom (replaced) – Symbol of the atom to be replaced (ex: ‘Sr’)

• dopant_atom (str) – Symbol of the dopant_atom (ex: ‘Eu’)

Return type:

list[Structure]

get_trans_vect(scale_matrix)

Returns the translation vectors for a given scale matrix.

Parameters:

scale_matrix – Scale matrix defining the new lattice vectors in term of the old ones

Return: the translation vectors

write_vib_file(xyz_file, qpoint, displ, do_real=True, frac_coords=True, scale_matrix=None, max_supercell=None)

Write into the file descriptor xyz_file the positions and displacements of the atoms

Parameters:

• xyz_file – file_descriptor

• qpoint – qpoint to be analyzed

• displ – eigendisplacements to be analyzed

• do_real – True if you want to get only real part, False means imaginary part

• frac_coords – True if the eigendisplacements are given in fractional coordinates

• scale_matrix – Scale matrix for supercell

• max_supercell – Maximum size of supercell vectors with respect to primitive cell

Return type:

None

frozen_2phonon(qpoint, displ1, displ2, eta=1, frac_coords=False, scale_matrix=None, max_supercell=None)

Creates the supercell needed for a given qpoint and adds the displacements. The displacements are normalized so that the largest atomic displacement will correspond to the value of eta in Angstrom.

Parameters:

• qpoint – q vector in reduced coordinate in reciprocal space.

• displ1 – first displacement in real space of the atoms.

• displ2 – second displacement in real space of the atoms.

• eta – pre-factor multiplying the displacement. Gives the value in Angstrom of the largest displacement.

• frac_coords – whether the displacements are given in fractional or cartesian coordinates

• scale_matrix – the scaling matrix of the supercell. If None a scaling matrix suitable for the qpoint will be determined.

• max_supercell – mandatory if scale_matrix is None, ignored otherwise. Defines the largest supercell in the search for a scaling matrix suitable for the q point.

Returns:

A namedtuple with a Structure with the displaced atoms, a numpy array containing the displacements applied to each atom and the scale matrix used to generate the supercell.

frozen_phonon(qpoint, displ, eta=1, frac_coords=False, scale_matrix=None, max_supercell=None)

Creates a supercell with displaced atoms for the specified q-point. The displacements are normalized so that the largest atomic displacement will correspond to the value of eta in Angstrom.

Parameters:

• qpoint – q-vector in reduced coordinate in reciprocal space.

• displ – displacement in real space of the atoms.

• eta – pre-factor multiplying the displacement. Gives the value in Angstrom of the largest displacement.

• frac_coords – whether the displacements are given in fractional or cartesian coordinates

• scale_matrix – the scaling matrix of the supercell. If None a scaling matrix suitable for the qpoint will be determined.

• max_supercell – mandatory if scale_matrix is None, ignored otherwise. Defines the largest supercell in the search for a scaling matrix suitable for the input q-point.

Returns:

A namedtuple with a Structure with the displaced atoms, a numpy array containing the displacements applied to each atom and the scale matrix used to generate the supercell.

calc_kptbounds()

Returns the suggested value for the ABINIT variable kptbounds.

Return type:

array

get_kpath_input_string(fmt='abinit', line_density=10)

Return string with input variables for band-structure calculations in the format used by code fmt. Use line_density points for the smallest segment (if supported by code).

Return type:

str

calc_ksampling(nksmall, symprec=0.01, angle_tolerance=5)

Return the k-point sampling from the number of divisions nksmall to be used for the smallest reciprocal lattice vector.

Return type:

AttrDict

calc_ngkpt(nksmall)

Compute the ABINIT variable ngkpt from the number of divisions used for the smallest lattice vector.

Parameters:

nksmall (int) – Number of division for the smallest lattice vector.

Return type:

ndarray

as_ngkpt(ngkpt)

Flexible API to compute the ABINIT variable ngkpt using different approaches.

Return type:

ndarray

The following cases are supported:

• If ngkpt is a 1D vector with 3 items, return ngkpt as-is.

• If ngkpt is a positive float, interpret it as nksmall (a scaling factor for the k-point grid).

• If ngkpt is a negative float, interpret it as the desired number of k-points per atom.

This method allows users to flexibly specify the k-point grid based on their preferred input format.

calc_shiftk(symprec=0.01, angle_tolerance=5)

Find the values of shiftk and nshiftk appropriated for the sampling of the Brillouin zone.

When the primitive vectors of the lattice do NOT form a FCC or a BCC lattice, the usual (shifted) Monkhorst-Pack grids are formed by using nshiftk=1 and shiftk 0.5 0.5 0.5 . This is often the preferred k point sampling. For a non-shifted Monkhorst-Pack grid, use nshiftk=1 and shiftk 0.0 0.0 0.0, but there is little reason to do that.

When the primitive vectors of the lattice form a FCC lattice, with rprim:

0.0 0.5 0.5
0.5 0.0 0.5
0.5 0.5 0.0

the (very efficient) usual Monkhorst-Pack sampling will be generated by using nshiftk= 4 and shiftk:

0.5 0.5 0.5
0.5 0.0 0.0
0.0 0.5 0.0
0.0 0.0 0.5

When the primitive vectors of the lattice form a BCC lattice, with rprim:

-0.5  0.5  0.5
 0.5 -0.5  0.5
 0.5  0.5 -0.5

the usual Monkhorst-Pack sampling will be generated by using nshiftk= 2 and shiftk:

 0.25  0.25  0.25
-0.25 -0.25 -0.25

However, the simple sampling nshiftk=1 and shiftk 0.5 0.5 0.5 is excellent.

For hexagonal lattices with hexagonal axes, e.g. rprim:

 1.0  0.0       0.0
-0.5  sqrt(3)/2 0.0
 0.0  0.0       1.0

one can use nshiftk= 1 and shiftk 0.0 0.0 0.5 In rhombohedral axes, e.g. using angdeg 3*60., this corresponds to shiftk 0.5 0.5 0.5, to keep the shift along the symmetry axis.

Return type:

ndarray

Returns:

Suggested value of shiftk.

num_valence_electrons(pseudos)

Returns the number of valence electrons.

Parameters:

pseudos – List of pymatgen.io.abinit.pseudos.Pseudo objects or list of filenames.

Return type:

float

valence_electrons_per_atom(pseudos)

Returns the number of valence electrons for each atom in the structure.

Parameters:

pseudos – List of pymatgen.io.abinit.pseudos.Pseudo objects or list of filenames.

Return type:

list

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporary file in the current working directory is created. Return path to the notebook.

Return type:

str

abipy.core.structure.dataframes_from_structures(struct_objects, index=None, symprec=0.01, angle_tolerance=5, with_spglib=True, cart_coords=False)

Build two pandas Dataframes with the most important geometrical parameters associated to a list of structures or a list of objects that can be converted into structures.

Parameters:

• struct_objects – List of objects that can be converted to structure. Support filenames, structure objects, Abinit input files, dicts and many more types. See Structure.as_structure for the complete list.

• index – Index of the pandas.DataFrame.

• symprec (float) – Symmetry precision used to refine the structure.

• angle_tolerance (float) – Tolerance on angles.

• with_spglib (bool) – If True, spglib is invoked to get the spacegroup symbol and number.

• cart_coords – True if the coords dataframe should contain Cartesian coordinates instead of Reduced coordinates.

Returns:

namedtuple with two pandas.DataFrame named lattice and coords lattice contains the lattice parameters. coords the atomic positions.. The list of structures is available in the structures entry.

dfs = dataframes_from_structures(files)
dfs.lattice
dfs.coords
for structure in dfs.structures:
    print(structure)

abipy.core.symmetries module

Objects used to deal with symmetry operations in crystals.

class abipy.core.symmetries.LatticeRotation(mat)

Bases: Operation

This object defines a pure rotation of the lattice (proper, improper, mirror symmetry) that is a rotation which is compatible with a lattice. The rotation matrix is expressed in reduced coordinates, therefore its elements are integers.

See:

http://xrayweb2.chem.ou.edu/notes/symmetry.html#rotation

Note

This object is immutable and therefore we do not inherit from numpy.ndarray.

inverse()

Invert an orthogonal 3x3 matrix of INTEGER elements. Note use of integer arithmetic. Raise ValueError if not invertible.

property isE

True if it is the identity

property order

Order of the rotation.

property root_inv

property det

Return the determinant of a symmetry matrix mat[3,3]. It must be +-1

property trace

The trace of the rotation matrix

property is_proper

True if proper rotation

property isI

True if self is the inversion operation.

property name

class abipy.core.symmetries.AbinitSpaceGroup(spgid, symrel, tnons, symafm, has_timerev, inord='C')

Bases: OpSequence

Container storing the space group symmetries.

classmethod from_ncreader(r, inord='F')

Builds the object from a netcdf reader

Return type:

AbinitSpaceGroup

classmethod from_structure(structure, has_timerev=True, symprec=1e-05, angle_tolerance=5)

Takes a abipy.core.structure.Structure object. Uses spglib to perform various symmetry finding operations.

Parameters:

• structure – abipy.core.structure.Structure object.

• has_timerev – True is time-reversal symmetry is included.

• symprec – Tolerance for symmetry finding.

• angle_tolerance – Angle tolerance for symmetry finding.

Warning

AFM symmetries are not supported.

to_string(verbose=0)

String representation.

Return type:

str

property is_symmorphic: bool

True if there’s at least one operation with non-zero fractional translation.

property has_timerev: bool

True if time-reversal symmetry is present.

property symrel

[nsym, 3, 3] int array with symmetries in reduced coordinates of the direct lattice.

property tnons

[nsym, 3] float array with fractional translations in reduced coordinates of the direct lattice.

property symrec

[nsym, 3, 3] int array with symmetries in reduced coordinates of the reciprocal lattice.

property symafm

[nsym] int array with +1 if FM or -1 if AFM symmetry.

property num_spatial_symmetries: int

property afm_symmops

Tuple with antiferromagnetic symmetries.

property fm_symmops

Tuple of ferromagnetic symmetries.

symmops(time_sign=None, afm_sign=None)

Parameters:

• time_sign – If specified, only symmetries with time-reversal sign time_sign are returned.

• afm_sign – If specified, only symmetries with anti-ferromagnetic part afm_sign are returned.

Returns:

tuple of SymmOp instances.

symeq(k1_frac_coords, k2_frac_coords, atol=None)

Test whether two k-points in fractional coordinates are symmetry equivalent i.e. if there’s a symmetry operations TO (including time-reversal T, if present) such that:

TO(k1) = k2 + G0

Return: namedtuple with:

isym: The index of the symmetry operation such that TS(k1) = k2 + G0
    Set to -1 if k1 and k2 are not related by symmetry.
op: Symmetry operation.
g0: numpy vector.

find_little_group(kpoint)

Find the little group of the kpoint.

Parameters:

kpoint – Accept vector with the reduced coordinates or Kpoint object.

Returns:

LittleGroup object.

get_spglib_hall_number(symprec=1e-05)

Uses spglib.get_hall_number_from_symmetry to determine the hall number based on the symmetry operations. Useful when the space group number is not available, but the symmetries are (e.g. the DDB file)

Parameters:

symprec – distance tolerance in fractional coordinates (not the standard in cartesian coordinates). See spglib docs for more details.

Returns:

the hall number.

Return type:

int

abipy.core.testing module