sisl.io.siesta.stdoutSileSiesta
- class sisl.io.siesta.stdoutSileSiesta(filename, *args, **kwargs)
Bases:
SileSiesta
Output file from Siesta
This enables reading the output quantities from the Siesta output.
Plotting
Plotting functions for the
stdoutSileSiesta
class.plot.geometry
([skip_input, ...])Calls
read_geometry
and creates aGeometryPlot
from its output.Methods
base_directory
([relative_to])Retrieve the base directory of the file, relative to the path relative_to
close
()True if the full file has been read and "Job completed" was found.
dir_file
([filename, filename_base])File of the current Sile
read
(*args, **kwargs)Generic read method which should be overloaded in child-classes
Reads the basis as found in the output file
read_charge
(name[, iscf, imd, key_scf, ...])Read charges calculated in SCF loop or MD loop (or both)
read_data
(*args, **kwargs)Read specific content in the Siesta out file
Reads the final energy distribution
read_force
([total, max, key, skip_final])Reads the forces from the Siesta output file
read_geometry
([skip_input])Reads the geometry from the Siesta output file
read_moment
([orbitals, quantity])Reads the moments from the Siesta output file
read_scf
([key, iscf, as_dataframe, ret_header])Parse SCF information and return a table of SCF information depending on what is requested
read_stress
([key, skip_final])Reads the stresses from the Siesta output file
write
(*args, **kwargs)Generic write method which should be overloaded in child-classes
Attributes
File of the current Sile
File of the current Sile
- base_directory(relative_to='.')
Retrieve the base directory of the file, relative to the path relative_to
- close()
- dir_file(filename=None, filename_base='')
File of the current Sile
- plot.geometry(skip_input: bool = True, *, axes: Axes = ['x', 'y', 'z'], atoms: AtomsIndex = None, atoms_style: Sequence[AtomsStyleSpec] = [], atoms_scale: float = 1.0, atoms_colorscale: Colorscale | None = None, drawing_mode: Literal['scatter', 'balls', None] = None, bind_bonds_to_ats: bool = True, points_per_bond: int = 20, bonds_style: StyleSpec = {}, bonds_scale: float = 1.0, bonds_colorscale: Colorscale | None = None, show_atoms: bool = True, show_bonds: bool = True, show_cell: Literal['box', 'axes', False] = 'box', cell_style: StyleSpec = {}, nsc: tuple[int, int, int] = (1, 1, 1), atoms_ndim_scale: tuple[float, float, float] = (16, 16, 1), bonds_ndim_scale: tuple[float, float, float] = (1, 1, 10), dataaxis_1d: np.ndarray | Callable | None = None, arrows: Sequence[AtomArrowSpec] = (), backend='plotly') GeometryPlot
Calls
read_geometry
and creates aGeometryPlot
from its output.- Parameters:
skip_input – the input geometry may be contained as a print-out. This is not part of an MD calculation, and hence is by default not returned.
axes – The axes to project the geometry to.
atoms – The atoms to plot. If None, all atoms are plotted.
atoms_style – List of style specifications for the atoms. See the showcase notebooks for examples.
atoms_scale – Scaling factor for the size of all atoms.
atoms_colorscale – Colorscale to use for the atoms in case the color attribute is an array of values. If None, the default colorscale is used for each backend.
drawing_mode – The method used to draw the atoms.
bind_bonds_to_ats – Whether to display only bonds between atoms that are being displayed.
points_per_bond – When the points are drawn using points instead of lines (e.g. in some frameworks to draw multicolor bonds), the number of points used per bond.
bonds_style – Style specification for the bonds. See the showcase notebooks for examples.
bonds_scale – Scaling factor for the width of all bonds.
bonds_colorscale – Colorscale to use for the bonds in case the color attribute is an array of values. If None, the default colorscale is used for each backend.
show_atoms – Whether to display the atoms.
show_bonds – Whether to display the bonds.
show_cell – Mode to display the cell. If False, the cell is not displayed.
cell_style – Style specification for the cell. See the showcase notebooks for examples.
nsc – Number of unit cells to display in each direction.
atoms_ndim_scale – Scaling factor for the size of the atoms for different dimensionalities (1D, 2D, 3D).
bonds_ndim_scale – Scaling factor for the width of the bonds for different dimensionalities (1D, 2D, 3D).
dataaxis_1d – Only meaningful for 1D plots. The data to plot on the Y axis.
arrows – List of arrow specifications to display. See the showcase notebooks for examples.
backend – The backend to use to generate the figure.
See also
GeometryPlot
The plot class used to generate the plot.
read_geometry
The method called to get the data.
- read(*args, **kwargs)
Generic read method which should be overloaded in child-classes
- Parameters:
kwargs – keyword arguments will try and search for the attribute
read_<>
and call it with the remaining**kwargs
as arguments.
- read_basis() Atoms [source]
Reads the basis as found in the output file
This parses 3 things:
At the start of the file there are some initatom output specifying which species in the calculation.
Reading the <basis_specs> entries for the masses
Reading the PAO.Basis block output for orbital information
- read_charge(name: Literal['voronoi', 'hirshfeld', 'mulliken'], iscf=Opt.ANY, imd=Opt.ANY, key_scf: str = 'scf', as_dataframe: bool = False)[source]
Read charges calculated in SCF loop or MD loop (or both)
Siesta enables many different modes of writing out charges.
The below table shows a list of different cases that may be encountered, the letters are referred to in the return section to indicate what is returned.
Case
A
B
C
D
E
Charge
MD
SCF
MD+SCF
Final
Orbital resolved
Voronoi
Hirshfeld
Mulliken
Notes
Errors will be raised if one requests information not present. I.e. passing an integer or Opt.ALL for iscf will raise an error if the SCF charges are not present. For Opt.ANY it will return the most information, effectively SCF will be returned if present.
Currently orbitally-resolved Mulliken is not implemented, any help in reading this would be very welcome.
- Parameters:
name – the name of the charges that you want to read
iscf (
int
orOpt
, optional) – index (0-based) of the scf iteration you want the charges for. If the enum specifier Opt.ANY or Opt.ALL are used, then the returned quantities depend on what is present. IfNone/Opt.NONE
it will not return any SCF charges. If both imd and iscf areNone
then only the final charges will be returned.imd (
int
orOpt
, optional) – index (0-based) of the md step you want the charges for. If the enum specifier Opt.ANY or Opt.ALL are used, then the returned quantities depend on what is present. IfNone/Opt.NONE
it will not return any MD charges. If both imd and iscf areNone
then only the final charges will be returned.key_scf – the key lookup for the scf iterations (a “:” will automatically be appended)
as_dataframe – whether charges should be returned as a pandas dataframe.
- Returns:
numpy.ndarray
– if a specific MD+SCF index is requested (or special cases where output is not complete)list
ofnumpy.ndarray
– if iscf or imd is different fromNone/Opt.NONE
.pandas.DataFrame
– if as_dataframe is requested. The dataframe will have multi-indices if multiple SCF or MD steps are requested.
- read_data(*args, **kwargs) Any [source]
Read specific content in the Siesta out file
The currently implemented things are denoted in the parameters list. Note that the returned quantities are in the order of keywords, so:
>>> read_data(geometry=True, force=True) <geometry>, <force> >>> read_data(force=True, geometry=True) <force>, <geometry>
- Parameters:
geometry (
bool
, optional) – read geometry, args are passed toread_geometry
force (
bool
, optional) – read force, args are passed toread_force
stress (
bool
, optional) – read stress, args are passed toread_stress
moment (
bool
, optional) – read moment, args are passed toread_moment
(only for spin-orbit calculations)energy (
bool
, optional) – read final energies, args are passed toread_energy
- read_energy() PropertyDict [source]
Reads the final energy distribution
Currently the energies translated are:
band
band structure energy
kinetic
electronic kinetic energy
hartree
electronic electrostatic Hartree energy
dftu
DFT+U energy
spin_orbit
spin-orbit energy
extE
external field energy
xc
exchange-correlation energy
exchange
exchange energy
correlation
correlation energy
bulkV
bulk-bias correction energy
total
total energy
negf
NEGF energy
fermi
Fermi energy
ion.electron
ion-electron interaction energy
ion.ion
ion-ion interaction energy
ion.kinetic
kinetic ion energy
basis.enthalpy
enthalpy of basis sets, Free + p_basis*V_orbitals
Any unrecognized key gets added as is.
Examples
>>> energies = sisl.get_sile("RUN.out").read_energy() >>> ion_energies = energies.ion >>> ion_energies.ion # ion-ion interaction energy >>> ion_energies.kinetic # ion kinetic energy >>> energies.fermi # fermi energy
- Returns:
PropertyDict (
dictionary like lookup table ionic energies are stored in a nested `PropertyDict
at the keyion
(all energies in eV)`)
- read_force(total: bool = False, max: bool = False, key: Literal['siesta', 'ts'] = 'siesta', skip_final: bool | None = None)[source]
Reads the forces from the Siesta output file
- Parameters:
total – return the total forces instead of the atomic forces.
max – whether only the maximum atomic force should be returned for each step.
Setting it to True is equivalent to max(outSile.read_force()) in case atomic forces are written in the output file (WriteForces .true. in the fdf file)
Note that this is not the same as doing max(outSile.read_force(total=True)) since the forces returned in that case are averages on each axis.
key – Specifies the indicator string for the forces that are to be read. The function will look for a line containing
f'{key}: Atomic forces'
to start reading forces.skip_final – the final output of the forces is duplicated when the final output is written. By default, this method will return the final forces, but only if no other forces are found. If forces from dynamics are found, then the final forces will not be returned, unless explicitly requested through this flag.
- Returns:
numpy.ndarray
orNone
– returnsNone
if the forces are not found in the output, otherwise forces will be returned- The shape of the array will be different depending on the type of forces requested:
atomic (default): (nMDsteps, nAtoms, 3)
total: (nMDsteps, 3)
max: (nMDsteps, )
If total and max are both True, they are returned separately as a tuple:
(total, max)
Notes
This method defaults to return the first item(s).
This method enables slicing for handling multiple values (see
[...|default]
).This is an optional handler enabling returning multiple elements if
read_force[...|0]
allows this.>>> single = obj.read_force() # returns the default entry of read_force[...|0]
To retrieve the first two elements that
read_force
will return>>> first_two = obj.read_force[:2]()
Retrieving the last two is done equivalently:
>>> last_two = obj.read_force[-2:]()
While one can store the sliced function
tmp = obj.read_force[:]
one will loose the slice after each call.
- read_geometry(skip_input: bool = True) Geometry [source]
Reads the geometry from the Siesta output file
- Parameters:
skip_input – the input geometry may be contained as a print-out. This is not part of an MD calculation, and hence is by default not returned.
- Returns:
geometries (
list
orGeometry
orNone
) – if all is False only one geometry will be returned (or None). Otherwise a list of geometries corresponding to the MD-runs.
Notes
This method defaults to return the first item(s).
This method enables slicing for handling multiple values (see
[...|default]
).This is an optional handler enabling returning multiple elements if
read_geometry[...|0]
allows this.>>> single = obj.read_geometry() # returns the default entry of read_geometry[...|0]
To retrieve the first two elements that
read_geometry
will return>>> first_two = obj.read_geometry[:2]()
Retrieving the last two is done equivalently:
>>> last_two = obj.read_geometry[-2:]()
While one can store the sliced function
tmp = obj.read_geometry[:]
one will loose the slice after each call.
- read_moment(orbitals: bool = False, quantity: Literal['S', 'L'] = 'S') ndarray [source]
Reads the moments from the Siesta output file
These will only be present in case of spin-orbit coupling.
- Parameters:
orbitals – return a table with orbitally resolved moments.
quantity – return the spin-moments or the L moments
Notes
This method defaults to return the first item(s).
This method enables slicing for handling multiple values (see
[...|default]
).This is an optional handler enabling returning multiple elements if
read_moment[...|0]
allows this.>>> single = obj.read_moment() # returns the default entry of read_moment[...|0]
To retrieve the first two elements that
read_moment
will return>>> first_two = obj.read_moment[:2]()
Retrieving the last two is done equivalently:
>>> last_two = obj.read_moment[-2:]()
While one can store the sliced function
tmp = obj.read_moment[:]
one will loose the slice after each call.
- read_scf(key: str = 'scf', iscf: int | None = -1, as_dataframe: bool = False, ret_header: bool = False)[source]
Parse SCF information and return a table of SCF information depending on what is requested
- Parameters:
key (
{'scf', 'ts-scf'}
) – parse SCF information from Siesta SCF or TranSiesta SCFiscf – which SCF cycle should be stored. If
-1
only the final SCF step is stored, for None all SCF cycles are returned. When iscf values queried are not found they will be truncated to the nearest SCF step.as_dataframe – whether the information should be returned as a
pandas.DataFrame
. The advantage of this format is that everything is indexed and therefore you know what each value means.You can also perform operations very easily on a dataframe.ret_header – whether to also return the headers that define each value in the returned array, will have no effect if as_dataframe is true.
Notes
This method defaults to return the last item(s).
This method enables slicing for handling multiple values (see
[...|default]
).This is an optional handler enabling returning multiple elements if
read_scf[...|-1]
allows this.>>> single = obj.read_scf() # returns the default entry of read_scf[...|-1]
To retrieve the first two elements that
read_scf
will return>>> first_two = obj.read_scf[:2]()
Retrieving the last two is done equivalently:
>>> last_two = obj.read_scf[-2:]()
While one can store the sliced function
tmp = obj.read_scf[:]
one will loose the slice after each call.
- read_stress(key: Literal['static', 'total', 'Voigt'] = 'static', skip_final: bool | None = None) ndarray [source]
Reads the stresses from the Siesta output file
- Parameters:
key – which stress to read from the output.
skip_final – the final output of the stress is duplicated when the final output is written. By default, this method will return the final stress, but only if no other stresses are found. If stresses from dynamics are found, then the final stress will not be returned, unless explicitly requested through this flag.
- Returns:
numpy.ndarray
orNone
– returnsNone
if the stresses are not found in the output, otherwise stresses will be returned
Notes
This method defaults to return the first item(s).
This method enables slicing for handling multiple values (see
[...|default]
).This is an optional handler enabling returning multiple elements if
read_stress[...|0]
allows this.>>> single = obj.read_stress() # returns the default entry of read_stress[...|0]
To retrieve the first two elements that
read_stress
will return>>> first_two = obj.read_stress[:2]()
Retrieving the last two is done equivalently:
>>> last_two = obj.read_stress[-2:]()
While one can store the sliced function
tmp = obj.read_stress[:]
one will loose the slice after each call.
- write(*args, **kwargs)
Generic write method which should be overloaded in child-classes
- Parameters:
**kwargs – keyword arguments will try and search for the attribute write_ and call it with the remaining
**kwargs
as arguments.
- property base_file
File of the current Sile
- property file
File of the current Sile
- plot
Plotting functions for the
stdoutSileSiesta
class.