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.

Methods

base_directory([relative_to])

Retrieve the base directory of the file, relative to the path relative_to

close()

completed()

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

read_basis()

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

read_energy()

Reads the final energy distribution

read_force([last, all, total, max, key])

Reads the forces from the Siesta output file

read_geometry([last, all])

Reads the geometry from the Siesta output file

read_moment([orbitals, quantity, last, all])

Reads the moments from the Siesta output file

read_scf([key, iscf, imd, as_dataframe, ...])

Parse SCF information and return a table of SCF information depending on what is requested

read_stress([key, last, all])

Reads the stresses from the Siesta output file

write(*args, **kwargs)

Generic write method which should be overloaded in child-classes

base_file

File of the current Sile

file

File of the current Sile

class InfoAttr(attr, regex, parser, doc='', updatable=False, default=None, found=False)

Bases: object

Holder for parsing lines and extracting information from text files

This consists of:

attr:

the name of the attribute This will be the sile.info. access point.

regex:

the regular expression used to match a line. If a str, it will be compiled as is to a regex pattern. regex.match(line) will be used to check if the value should be updated.

parser:

if regex.match(line) returns a match that is true, then this parser will be executed. The parser must be a function accepting two arguments:

def parser(attr, match)

where attr is this object, and match is the match done on the line. (Note that match.string will return the full line used to match against).

updatable:

control whether a new match on the line will update using parser. If false, only the first match will update the value

default:

the default value of the attribute

found:

whether the value has been found in the file.

__init__(attr, regex, parser, doc='', updatable=False, default=None, found=False)
attr
copy()
doc
documentation()

Returns a documentation string for this object

found
parser
process(line)
regex
updatable
value
__init__(filename, mode='r', *args, **kwargs)

Just to pass away the args and kwargs

base_directory(relative_to='.')

Retrieve the base directory of the file, relative to the path relative_to

property base_file

File of the current Sile

close()
completed()[source]

True if the full file has been read and “Job completed” was found.

dir_file(filename=None, filename_base='')

File of the current Sile

property file

File of the current Sile

plot

Handles all plotting possibilities for a class

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()[source]

Reads the basis as found in the output file

This parses 3 things:

  1. At the start of the file there are some initatom output specifying which species in the calculation.

  2. Reading the <basis_specs> entries for the masses

  3. Reading the PAO.Basis block output for orbital information

read_charge(name, iscf=Opt.ANY, imd=Opt.ANY, key_scf='scf', as_dataframe=False)[source]

Read charges calculated in SCF loop or MD loop (or both)

Siesta enables many different modes of writing out charges.

NOTE: currently Mulliken charges are not implemented.

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 Mulliken is not implemented, any help in reading this would be very welcome.

Parameters:
  • name ({"voronoi", "hirshfeld"}) – the name of the charges that you want to read

  • iscf (int or Opt, 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. If None/Opt.NONE it will not return any SCF charges. If both imd and iscf are None then only the final charges will be returned.

  • imd (int or Opt, 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. If None/Opt.NONE it will not return any MD charges. If both imd and iscf are None then only the final charges will be returned.

  • key_scf (str, optional) – the key lookup for the scf iterations (a “:” will automatically be appended)

  • as_dataframe (boolean, optional) – 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 of numpy.ndarray – if one both iscf or imd is different from None/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)[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 to read_geometry

  • force (bool, optional) – read force, args are passed to read_force

  • stress (bool, optional) – read stress, args are passed to read_stress

  • moment (bool, optional) – read moment, args are passed to read_moment (only for spin-orbit calculations)

  • energy (bool, optional) – read final energies, args are passed to read_energy

read_energy()[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

Return type:

dictionary like lookup table ionic energies are stored in a nested PropertyDict at the key ion (all energies in eV)

read_force(last=True, all=False, total=False, max=False, key='siesta')[source]

Reads the forces from the Siesta output file

Parameters:
  • last (bool, optional) – only read the last force

  • all (bool, optional) – return a list of all forces (like an MD) If True last is ignored

  • total (bool, optional) – return the total forces instead of the atomic forces.

  • max (bool, optional) –

    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 ({"siesta", "ts"}) – 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.

Returns:

returns None 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 all is False, the first dimension does not exist. In the case of max, the returned value will therefore be just a float, not an array.

If total and max are both True, they are returned separately as a tuple: (total, max)

Return type:

numpy.ndarray or None

read_geometry(last=True, all=False)[source]

Reads the geometry from the Siesta output file

Parameters:
  • last (bool, optional) – only read the last geometry

  • all (bool, optional) – return a list of all geometries (like an MD) If True last is ignored

Returns:

geometries – if all is False only one geometry will be returned (or None). Otherwise a list of geometries corresponding to the MD-runs.

Return type:

list or Geometry or None

read_moment(orbitals=False, quantity='S', last=True, all=False)[source]

Reads the moments from the Siesta output file

These will only be present in case of spin-orbit coupling.

Parameters:
  • orbitals (bool, optional) – return a table with orbitally resolved moments.

  • quantity ({'S', 'L'}, optional) – return the spin-moments or the L moments

  • last (bool, optional) – only read the last force

  • all (bool, optional) – return a list of all forces (like an MD) If True last is ignored

read_scf(key='scf', iscf=-1, imd=None, as_dataframe=False, ret_header=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 SCF

  • iscf (int, optional) – 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.

  • imd (int or None, optional) – whether only a particular MD step is queried, if None, all MD steps are parsed and returned. A negative number wraps for the last MD steps.

  • as_dataframe (boolean, optional) – 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 (bool, optional) – whether to also return the headers that define each value in the returned array, will have no effect if as_dataframe is true.

read_stress(key='static', last=True, all=False)[source]

Reads the stresses from the Siesta output file

Parameters:
  • key ({'static', 'total'}) – which stress to read from the output.

  • last (bool, optional) – only read the last stress

  • all (bool, optional) – return a list of all stresses (like an MD) If True last is ignored

Returns:

returns None if the stresses are not found in the output, otherwise stresses will be returned

Return type:

numpy.ndarray or None

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.