Manual

The complete WESTpy reference is reported below.

Units

Westpy uses Hartree atomic units.

class westpy.units.Units(*args, **kwargs)

Bases: dict

Dictionary for units that supports .attribute access.

westpy.units.set_units()

Sets Rydberg atomic units.

Available units are:
  • Bohr

  • Angstrom, Ang

  • Rydberg, Ry

  • Hartree, Ha

  • eV

  • Joule

Note

westpy operates in Rydberg atomic units.

Utilities

Set of utilities.

westpy.utils.bool2str(logical)

Converts a boolean type into a string .TRUE. or .FALSE. .

Parameters:

logical (boolean) – logical

Returns:

.TRUE. or .FALSE.

Return type:

string

Example:

>>> from westpy import *
>>> t = bool2str(True)
>>> f = bool2str(False)
>>> print(t,f)
.TRUE. .FALSE.
westpy.utils.convertYaml2Json(fyml, fjson)

Converts the file from YAML to JSON.

Parameters:
  • fyml (string) – Name of YAML file

  • fjson (string) – Name of JSON file

Example:

>>> from westpy import *
>>> convertYaml2Json("file.yml","file.json")

Note

The file fjson will be created, fyml will not be overwritten.

westpy.utils.download(url, fname=None)

Downloads a file from url.

Parameters:
  • url (string) – url

  • fname (string) – file name, optional

Example:

>>> from westpy import *
>>> download("http://www.west-code.org/database/gw100/xyz/CH4.xyz")

Note

The file will be downloaded in the current directory.

westpy.utils.extractFileNamefromUrl(url)

Extracts a file name from url.

Parameters:

url (string) – url

Returns:

file name

Return type:

string

Example:

>>> from westpy import *
>>> extractFileNamefromUrl("http://www.west-code.org/database/gw100/xyz/CH4.xyz")
westpy.utils.gaussian(x, mu, sig)

return normal distribution at point x.

\(f(x;\mu,\sigma) = \frac{1}{\sigma\sqrt{2\pi}}e^{-\frac{(x-\mu)^2}{2\sigma^2}}\)

Parameters:
Returns:

\(f(x;\mu,\sigma)\)

Return type:

float

Example:

>>> from westpy import *
>>> gaussian(1.0,2.0,3.0)
westpy.utils.listLinesWithKeyfromOnlineText(url, key)

List lines from text file located at url, with key.

Parameters:
  • url (string) – url

  • key (string) – key word

Returns:

list of lines

Return type:

list

Example:

>>> from westpy import *
>>> url = "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf"
>>> key = "z_valence"
>>> l = listLinesWithKeyfromOnlineText(url,key)
>>> print(l)
['       z_valence="    4.00"']

Note

Can be used to grep values from a UPF file.

westpy.utils.listValuesWithKeyFromOnlineXML(url, key)

List values from XML file located at url, with key.

Parameters:
  • url (string) – url

  • key (string) – key word

Returns:

list of values

Return type:

list

Example:

>>> from westpy import *
>>> url = "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/Si_ONCV_PBE-1.1.xml"
>>> key = "valence_charge"
>>> l = listLinesWithKeyfromOnlineXML(url,key)
>>> print(l)
['4']

Note

Can be used to grep values from an XML file.

westpy.utils.readJsonFile(fname)

Reads data from file using the JSON format.

Parameters:

fname (string) – file name

Returns:

data

Return type:

dict/list

Example:

>>> from westpy import *
>>> data = readJsonFile("mass.json")

Note

The file will be read from the current directory.

westpy.utils.read_cube(fname)

Read cube file into numpy array

Parameters:

fname (string) – filename of cube file

Returns:

(data, metadata)

Return type:

(np.array, dict)

westpy.utils.read_imcube(rfname, ifname='')

Convenience function to read in two cube files at once, where one contains the real part and the other contains the imag part. If only one filename given, other filename is inferred.

Parameters:
  • rfname (string) – filename of cube file of real part

  • ifname – optional, filename of cube file of imag part

Returns:

(data, metadata), where data is (real part + j*imag part)

Return type:

(np.array, dict)

westpy.utils.wfreq2df(fname='wfreq.json', dfKeys=['eks', 'eqpLin', 'eqpSec', 'sigmax', 'sigmac_eks', 'sigmac_eqpLin', 'sigmac_eqpSec', 'vxcl', 'vxcnl', 'hf'])

Loads the wfreq JSON output into a pandas dataframe.

Parameters:
  • fname (string) – filename of JSON output file

  • dfKeys (list of string) – energy keys to be added to dataframe

Returns:

(dataframe, data)

Return type:

(pd.DataFrame, dict)

westpy.utils.writeJsonFile(fname, data)

Writes data to file using the JSON format.

Parameters:
  • fname (string) – file name

  • data (dict/list) – data

Example:

>>> from westpy import *
>>> data = {}
>>> data["mass"] = 1.0
>>> writeJsonFile("mass.json",data)

Note

The file will be generated in the current directory.

westpy.utils.write_cube(data, meta, fname)

Write volumetric data to cube file along

Parameters:
  • data (list of float) – volumetric data consisting real values

  • meta (dict) –

    dict containing metadata with following keys:

    • atoms: list of atoms in the form (mass, [position])

    • org: origin

    • xvec,yvec,zvec: lattice vector basis

  • fname (string) – filename of cubefile (existing files overwritten)

westpy.utils.write_imcube(data, meta, rfname, ifname='')

Convenience function to write two cube files from complex valued volumetric data, one for the real part and one for the imaginary part. Data about atoms, origin and lattice vectors are kept same for both. If only one filename given, other filename is inferred.

Parameters:
  • data (list of complex) – volumetric data consisting complex values

  • meta (dict) –

    dict containing metadata with following keys:

    • atoms: list of atoms in the form (mass, [position])

    • org: origin

    • xvec,yvec,zvec: lattice vector basis

  • rfname (string) – filename of cubefile containing real part

  • ifname (string) – optional, filename of cubefile containing imag part

Atom

class westpy.atom.Atom(cell=None, ase_atom=None, symbol=None, cry_coord=None, abs_coord=None, **kwargs)

Bases: object

Class for representing a single atom.

An atom can be initialized by and exported to an ASE Atom object.

All internal quantities below are in atomic unit.

Attributes:

cell(Cell): the cell where the atom lives. symbol(str): chemical symbol of the atom. abs_coord(float array): absolute coordinate. cry_coord(float array): crystal coordinate.

Extra attributes can be attached to an atom.

property cry_coord

Geometry

class westpy.geometry.Geometry(cell=None)

Bases: object

Class for representing a set of atoms in a periodic cell.

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.setCell( (1,0,0), (0,1,0), (0,0,1) )
>>> geom.addAtom( symbol="Si", abs_coord=(0,0,0) )
>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" )

Note

Vectors are set in a.u. by default. If you set units=Angstrom a coversion to a.u. will be made.

Bohr = 1.0
addAtom(symbol, position, units=1.0)

Adds a single atom.

Parameters:
  • symbol (string) – chemical symbol

  • position (3-dim tuple) – position

  • units ("Bohr" or "Angstrom") – Units, optional

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtom( position="Si", abs_coord=(0,0,0) )
addAtomsFromOnlineXYZ(url)

Adds atoms from XYZ file (only one image) located at url.

Parameters:

url (string) – url

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
addAtomsFromXYZFile(fname)

Adds atoms from XYZ file (only one image).

Parameters:

fname (string) – file name

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomFromXYZFile( "CH4.xyz" )
addFracCoordAtom(symbol, frac_coord)

adds a single atom by fractional coords :param symbol: chemical symbol :type symbol: string :param position: position :type position: 3-dim tuple

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addFracCoordAtom( "Si", (0,1/3.0,2/3.0) )
addSpecies(symbol, url)

Adds a species.

Parameters:
  • symbol (string) – chemical symbol

  • url (string) – url

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" )

Note

You can use this method to add either upf or xml pseudopotentials. However it is forbidded to mix them.

downloadPseudopotentials()

Download Pseudopotentials.

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> geom.addSpecies( "C", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/C_ONCV_PBE-1.0.xml")
>>> geom.addSpecies( "H", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/H_ONCV_PBE-1.0.xml")
>>> geom.downloadPseudopotentials()

Note

Pseudopotential files will be downloaded in the current directory.

getNumberOfAtoms()

Returns number of atoms.

Returns:

number of atoms

Return type:

int

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> nat = geom.getNumberOfAtoms()
>>> print( nat )
5
getNumberOfElectrons()

Returns number of electrons.

Returns:

number of electrons

Return type:

int

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> geom.addSpecies( "C", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/C_ONCV_PBE-1.0.xml")
>>> geom.addSpecies( "H", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/H_ONCV_PBE-1.0.xml")
>>> nelec = geom.getNumberOfElectrons()
>>> print( nelec )
8
getNumberOfSpecies()

Returns number of species.

Returns:

number of species

Return type:

int

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> ntyp = geom.getNumberOfSpecies()
>>> print( ntyp )
2
isValid()

Checks if geometry is valid

The method checks that:
  • the cell is set

  • at least one atom has been added

  • the pseudopotentials of all species are defined

  • the pseudopotentials do not contain a mix of upf and xml formats

setCell(a1=(0, 0, 0), a2=(0, 0, 0), a3=(0, 0, 0), units=1.0)

Sets cell, given the three vectors \(a_1\), \(a_2\), \(a_3\).

Parameters:
  • a1 (3-dim tuple) – \(a_1\)

  • a2 (3-dim tuple) – \(a_2\)

  • a3 (3-dim tuple) – \(a_3\)

  • units ("Bohr" or "Angstrom") – Units, optional

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.setCell( (1,0,0), (0,1,0), (0,0,1) )
view(style='stick', width=800, height=800, ix=1, iy=1, iz=1, debug=False)

Display simulation box geom in Angstrom. ix, iy, iz is the perodic display to system style can be line, stick, sphere.

Parameters:
  • style

  • width

  • height

  • ix

  • iy

  • iz

  • debug

Returns:

Ground State

class westpy.groundState.GroundState(geom, xc, ecut)

Bases: object

Class for representing a ground state calculation with DFT.

Parameters:
  • geom (Class(Geometry)) – geometry (cell, atoms, species)

  • xc (string) – exchange-correlation functional

  • ecut (float) – energy cutoff for the wavefunction (in Rydberg units)

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.setCell( (1,0,0), (0,1,0), (0,0,1) )
>>> geom.addAtom( "Si", (0,0,0) )
>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" )
>>> gs = GroundState(geom,"PBE",30.0)

Note

Vectors are set in a.u. by default. If you set units=Angstrom a coversion to a.u. will be made.

downloadPseudopotentials()

Download Pseudopotentials.

Example:

>>> gs.downloadPseudopotentials()

Note

Pseudopotential files will be downloaded in the current directory.

generateInputPW(fname='pw.in')

Generates input file for pwscf. Valid only for QuantumEspresso calculations.

Parameters:

fname (string) – fname, optional

Example:

>>> gs.generateInputPW("pw.in")
generateInputQbox(fname='qbox.in')

Generates input file for qbox. Valid only for Qbox calculations.

Parameters:

fname (string) – fname, optional

Example:

>>> gs.generateInputQbox("qbox.in")
setCollinearSpin(tot_magnetization=0.0)

Sets collinear spin.

Parameters:

tot_magnetization (float) – Total majority spin charge - minority spin charge, optional

Example:

>>> gs.setCollinearSpin()
setIsolated()

Sets isolated system. Valid only for QuantumEspresso calculations.

Example:

>>> gs.setIsolated()
setKmesh(kmesh)

Sets the uniform grid for k-points sampling.

Parameters:

kmesh (3-dim tuple of int) – kmesh

Example:

>>> gs.setKmesh((2,2,2))
setNempty(nempty)

Sets the number of empty bands.

Parameters:

nempty (int) – number of empty bands

Example:

>>> gs.setNempty(10)
setNonCollinearSpin(lspinorb=False)

Sets non collinear spin. Requires fully relativistic pseudopotentials. Valid only for QuantumEspresso calculations.

Optionally spin-orbit can be turned on.

Parameters:

lspinorb (boolean) – spin-orbit, optional

Example:

>>> gs.setNonCollinearSpin()
updateSpecies(symbol, url)

Update a species.

Parameters:
  • symbol (string) – chemical symbol

  • url (string) – url

Example:

>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" )

Note

You can use this method to add either upf or xml pseudopotentials. However it is forbidded to mix them.

Data Container

class westpy.dataContainer.DataContainer

Bases: object

Class for representing an in-memory data container.

Example:

>>> from westpy import *
>>> dc = DataContainer()
checkKeys(printSummary=True)

Checks that all keys are described.

Parameters:
  • printSummary (boolean) – if True prints summary

  • key (string) – key

Returns:

True if all keys are described, False otherwise.

Return type:

boolean

Example:

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5})
>>> dc.upsertKey("a","the first letter")
>>> dc.upsertKey("b","another letter")
>>> dc.upsertKey("energy","a quantity")
>>> dc.checkKeys()
removeKey(key)

Removes the description of a key

Parameters:

key (string) – key

Example:

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertKey("a","the first letter")
>>> dc.removeKey("a")
removePoint(identifier)

Removes point with given identifier from the data container.

Parameters:

identifier – identifier

Example:

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5})
>>> dc.removePoint({"a":1, "b":2})
showPoints()

Shows all points of the data container.

Example:

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5})
>>> dc.showPoints()
upsertKey(key, description)

Updates or inserts a new key and its description.

Parameters:
  • key (string) – key

  • description – description

Example:

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertKey("a","the first letter")
upsertPoint(identifier, document, incremental_update=True)

Update or inserts an entry to the data container.

If identifier exists, update the document associated to the identifier, otherwise insert the document with the identifier.

Parameters:
  • identifier – identifier

  • document – document

  • incremental_update (boolean) – if the document exists, only update it, do not remove its other keys.

Example:

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5})

Electronic Structure

class westpy.electronicStructure.ElectronicStructure

Bases: object

Class for representing an electronic structure calculation.

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
addDataPoint(ksb, key, what)

Adds datapoint to data.

Parameters:
  • ksb (3-dim int) – triplet of integers: k-point, spin, band (integer labels)

  • key (string) – key

  • what – content attached to key

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham energy in eV")
>>> es.addDataPoint([1,1,1],"eks",-4.6789)
addKey(key, description)

Describes metadata key.

Parameters:
  • key (string) – key

  • description – description

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham")
plotDOS(kk=[1], ss=[1], energyKeys=['eks'], sigma=0.1, weight=1.0, energyRange=[-20.0, 0.0, 0.01], fname='dos.png')

Plots desnity of states (DOS).

Parameters:
  • kk (list of int) – list of k-points

  • ss (list of int) – list of spin channels (must be [1], [2], or [1,2])

  • energyKeys (list of string (needs to match the available keys)) – energy keys

  • sigma (float .OR. string (needs to match the available keys)) – standard deviation of gaussian (eV), optional

  • weight (float .OR. string (needs to match the available keys)) – weight, optional

  • energyRange (3-dim float) – energy range = min, max, step (eV), optional

  • fname (string) – output file name

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham energy in eV")
>>> es.addDataPoint([1,1,1],"eks",-4.6789)
>>> es.addDataPoint([1,1,2],"eks",-4.3456)
>>> es.addDataPoint([1,2,1],"eks",-4.4567)
>>> es.addDataPoint([1,2,2],"eks",-4.0123)
>>> es.plotDOS(kk=[1],ss=[1,2],energyKeys=["eks"],energyRange=[-5.,-3,0.01])
plotLDOS(kk=[1], ss=[1], energyKeys=['eks'], sigma=0.1, weight=1.0, energyRange=[-20.0, 0.0, 0.01], wfcKey='wfcFile', fname='ldos.png')

Plots desnity of states (DOS).

Parameters:
  • kk (list of int) – list of k-points

  • ss (list of int) – list of spin channels

  • energyKeys (list of string (needs to match the available keys)) – energy keys

  • sigma (float .OR. string (needs to match the available keys)) – standard deviation of gaussian (eV), optional

  • weight (float .OR. string (needs to match the available keys)) – weight, optional

  • energyRange (3-dim float) – energy range = min, max, step (eV), optional

  • wfcKey (string (needs to match the available keys)) – wavefunction file

  • fname (string) – output file name

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham energy in eV")
>>> es.addDataPoint([1,1,1],"eks",-4.6789)
>>> es.addDataPoint([1,1,2],"eks",-4.3456)
>>> es.addDataPoint([1,2,1],"eks",-4.4567)
>>> es.addDataPoint([1,2,2],"eks",-4.0123)
>>> es.plotLDOS(kk=[1],ss=[1,2],energyKeys=["eks"],energyRange=[-5.,-3,0.01])
removeKey(key)

Removes key from metadata.

Parameters:

key (string) – key

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham")
>>> es.removeKey("eks")
showKeys()

Shows keys in metadata.

Example:

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.showKeys()

Session

class westpy.session.Session(emailId)

Bases: object

Class for setting up a session, connected to a remove server via rest APIs.

Example:

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
getToken()

Returns the token of the session.

Example:

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> token = session.getToken()
>>> print(token)
run(executable=None, inputFile=None, outputFile=None, downloadUrl=[], number_of_cores=2)

Runs the executable on the remote server.

Parameters:
  • executable (string) – name of executable

  • inputFile (string) – name of input file

  • outputFile (string) – name of output file

  • downloadUrl (list of string) – URLs to be downloaded

  • number_of_cores (int) – number of cores

Example:

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> session.run( "pw", "pw.in", "pw.out", ["http://www.quantum-simulation.org/potentials/sg15_oncv/upf/C_ONCV_PBE-1.0.upf"] , 2 )
>>> session.stop()
status()

Returns whether the session is active and time left.

Example:

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> session.status()
stop()

Stops the session and clears the remote workspace.

Example:

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> session.stop()