pychemia.core package

PyChemia works with atomic structures, this module provides two main classes to store structure information. The class ‘Structure’ and the class ‘Composition’ are widely used for the entire package.

Subpackages

• pychemia.core.tests package
  • Submodules
  • pychemia.core.tests.test_core module
  • pychemia.core.tests.test_doctest module

Submodules

pychemia.core.composition module

class pychemia.core.composition.Composition(value=None)

Bases: collections.abc.Mapping

The class Composition is basically a dictionary with species as keys and number of atoms of that specie as values. The methods provided for Composition objects should not contain geometrical information or graph connectivity.

The main purpose of this class is to be able to parse formulas into compositions and return string formulas sorted in various ways.

composition

Returns:The composition dictionary Return type:dict

covalent_volume(packing='cubes')

Returns the volume occupied by a given formula assuming a ‘cubes’ packing or ‘spheres’ packing

Parameters:packing – (str) The kind of packing could be ‘cubes’ or ‘spheres’

:rtype : (float)

>>> import pychemia
>>> comp=pychemia.Composition('C5H10')
>>> comp.covalent_volume()
19.942320000000002
>>> comp.covalent_volume(packing='spheres')
10.441774334589468

formula

Returns:The chemical formula with atoms sorted alphabetically Return type:str

static formula_parser(value)

Returns:Convert an string representing a chemical formula into a dictionary with the species as keys and values as the number of atoms of that specie Parameters:value – (str) String representing a chemical formula Return type:dict

Examples: >>> import pychemia >>> import pprint >>> pychemia.Composition.formula_parser(‘Au20’) {u’Au’: 20} >>> ret = pychemia.Composition.formula_parser(‘UutUupUusUuo’) >>> pprint.pprint(ret) {u’Uuo’: 1, u’Uup’: 1, u’Uus’: 1, u’Uut’: 1}

static formula_to_list(formula, nunits=1)

Reads a formula and returns a list of atomic symbols consistent with the formula and the number of formulas given by nunits

Parameters:

• formula – (str) Chemical formula as string
• nunits – (int) Number of formulas to apply

:rtype : (list)

Examples: >>> import pychemia >>> pychemia.Composition.formula_to_list(‘NaCl’) [u’Na’, u’Cl’] >>> flist = pychemia.Composition.formula_to_list(u’Uut2Uup3Uus4Uuo5’) >>> len(flist) 14 >>> flist = pychemia.Composition.formula_to_list(‘Uut2Uup3Uus4Uuo5’, nunits=2) >>> len(flist) 28

gcd

The number of formulas that can be extracted from a composition The greatest common denominator for the composition.

Return type:(int)

Example: >>> import pychemia >>> comp = pychemia.Composition(‘NaCl’) >>> comp.gcd 1 >>> comp = pychemia.Composition(‘Na2Cl2’) >>> comp.gcd 2 >>> comp = pychemia.Composition() >>> comp.gcd is None True

static get_species_from_hex(arg)

Return a set of species from the encoded species hexadecimal representation.

Parameters:arg – str String with hexadecimal representation of list of species. Returns:

Example: >>> Composition.get_species_from_hex(‘0x38271d08’) [8, 29, 39, 56]

natom

Returns:The number of atoms in the composition Return type:int

nspecies

sorted_formula(sortby='alpha', reduced=True)

Returns:

The chemical formula. It could be sorted alphabetically using sortby=’alpha’, by electronegativity using sortby=’electroneg’ or using Hill System with sortby=’Hill’

Parameters:

• sortby – (str) ‘alpha’ : Alphabetically ‘electroneg’ : Electronegativity ‘hill’ : Hill System
• reduced – (bool) If the formula should be normalized

Return type:

str

>>> comp=Composition('YBa2Cu3O7')
>>> comp.sorted_formula()
u'Ba2Cu3O7Y'
>>> comp.sorted_formula(sortby='hill')
u'Ba2Cu3O7Y'
>>> comp.sorted_formula(sortby='electroneg')
u'Ba2YCu3O7'
>>> comp = Composition('H10C5')
>>> comp.sorted_formula(sortby='hill', reduced=True)
u'CH2'
>>> comp = Composition('IBr')
>>> comp.sorted_formula(sortby='hill', reduced=False)
u'BrI'
>>> comp = Composition('Cl4C')
>>> comp.sorted_formula(sortby='hill', reduced=False)
u'CCl4'
>>> comp = Composition('IH3C')
>>> comp.sorted_formula(sortby='hill', reduced=False)
u'CH3I'
>>> comp = Composition('BrH5C2')
>>> comp.sorted_formula(sortby='hill', reduced=False)
u'C2H5Br'
>>> comp = Composition('S04H2')
>>> comp.sorted_formula(sortby='hill', reduced=False)
u'H2S4'
>>> comp = Composition('SO4H2')
>>> comp.sorted_formula(sortby='hill', reduced=False)
u'H2O4S'

species

Returns:The list of species Return type:list

species_encoded(base)

species_hex()

Encodes the species into a hexadecimal representation where each specie is stored on a 2-Byte slot ordered by atomic number. This is a ‘confortable’ encoding where each 2 characters from the hexadecimal will encode a single species and the species are ordered by atomic number making the codification unique.

Returns:str

Example: >>> comp = Composition(‘YBa2Cu3O7’) >>> comp.species_hex() ‘0x38271d08’

symbols

values

Returns:The number of atoms of each specie Return type:list

pychemia.core.delaunay module

Delaunay Reduction

pychemia.core.delaunay.get_delaunay_reduction(lattice, tolerance)

Return a reduced cell using the delanuay reduction

Parameters:

• lattice – (numpy.ndarray) the cell parameters
• tolerance – (float) Tolerance used to reduce basis

Returns:

(numpy.ndarray) a new cell

pychemia.core.delaunay.get_reduced_bases(cell, tolerance=1e-05)

This is an implementation of Delaunay reduction. Some information is found in International table.

Parameters:

• cell – (numpy.ndarray) Cell parameters dimension 3x3
• tolerance – (float) Tolerance used to reduce basis

Returns:

(numpy.ndarray) a new cell

pychemia.core.delaunay.get_shortest_bases_from_extented_bases(extended_bases, tolerance)

pychemia.core.delaunay.reduce_bases(extended_bases, tolerance)

Reduces the basis with a given tolerance

Parameters:

• extended_bases –
• tolerance – (float) Tolerance used by reduction algorithm

pychemia.core.from_file module

pychemia.core.from_file.structure_from_file(structure_file)

pychemia.core.structure module

Definition of the class Structure This class defines methods to create and manipulate atomic structures such as molecules, clusters and crystals

class pychemia.core.structure.Site(symbols, occupancies, position, reduced=None)

Bases: object

class pychemia.core.structure.SiteSet(structure)

Bases: object

class pychemia.core.structure.Structure(**kwargs)

Bases: collections.abc.MutableSequence

Define an object that contains information about atomic positions, cell parameters and periodicity and provides methods to manipulate those elements

A Structure is basically a set of sites with eventually a lattice each site could have one or more species with occupations equal or lower than one.

A Structure could represents a molecule, cluster, wire, slab, crystal structure or alloy with define sites. The positions of the atoms and their atomic symbols are declared in ‘positions’ and ‘symbols’ respectively.

For periodic structures, the ‘periodicity’ can be declared. and cell parameters in ‘cell’

Magnetic moments can be associated in the array vector_info[‘magnetic_moments’].

add_atom(name, coordinates, option='cartesian')

Add an atom with a given ‘name’ and cartesian or reduced ‘position’ The atom will be added at the end of the list of atoms in the Structure

Parameters:

• name – (str)
• coordinates – (list, numpy.array)
• option – (str)

add_vacuum(length, direction=2)

adjust_reduced()

align_inertia_momenta()

align_with_axis(axis=0, round_decimals=14)

align_with_plane(axis=2, round_decimals=14)

atoms_in_box()

canonical_form()

center_mass(list_of_atoms=None)

Computes the center of mass (CM) of the XYZ object or a partial list of atoms. The default is to compute the CM of all the atoms in the object, if a list is enter only those in the list will be included for the CM Return the CM as a numpy array

composition

Dictionary with the composition, the keys are the species and the values represent the number of atoms of that specie

:rtype : dict

Returns:dict

copy()

Get a copy of the object

del_atom(index)

Removes the atom with the given index

Parameters:index – Returns:

density

Computes the density of the cell

Return type:float Returns:float

distance2(atom1, atom2)

distance_matrix()

formula

String with the chemical formula

Return type:str Returns:str

static from_dict(structdict)

get_cell()

get_composition(gcd=True)

Computes the composition of the Structure as the count of each species in the cell If gcd is True the values are divided by the greatest common divisor

Parameters:gcd – bool

:rtype : Composition

get_distance(iatom, jatom, with_periodicity=True, tolerance=1e-05)

Calculates the distance between 2 atom, identified by index iatom and jatom

Parameters:

• iatom – (int) index of first atom
• jatom – (int) index of second atom
• with_periodicity – (bool) if the periodic images should be considered to compute the shortest distance
• tolerance – (float) Tolerance for the bases reduction

:rtype : (float) distance between iatom and jatom

inertia_matrix()

insert(index, value)

is_crystal

True if structure is periodic in all directions False otherwise

:rtype : bool

Returns:bool

is_perfect

Return True if two conditions are met:

1. The number of sites is equal to the number of atoms. ie there is no more than one atom on each site.

2. All the occupancies are equal to 1

:rtype : bool

Returns:bool

is_periodic

Return True if the Structure is periodic in any direction False for non-periodic structures

:rtype : bool

Returns:bool

lattice

static load_json(filename)

moment_of_inertia(axis)

nsites

nspecies

positions2reduced()

Computes the cell-reduced coordinates from the cartesian dimensional coordinates

product_of_inertia(axis)

static random_cell(composition, method='stretching', stabilization_number=20, nparal=5, periodic=True, factor_optimal_volume=8)

Generate a random cell There are two algorithms implemented:

scaling: Generate a random cell and random distribution of atoms and

scale the lattice to separate the atoms.

stretching: Generating a random cell and random distribution of atoms

and stretching their bonds until the distance between any two atoms is always greater than the sum of covalent radius.

Parameters:

• composition – (pychemia.Composition)
• method – (str)
• stabilization_number – (int)
• nparal – (int)
• periodic – (bool)
• factor_optimal_volume – (float)

Returns:

Examples: >>> import pychemia >>> import os >>> st = pychemia.Structure.random_cell(‘LiAlCl4’, stabilization_number=3) >>> st.natom 6 >>> st.save_json(‘test.json’) >>> st2 = pychemia.Structure.load_json(‘test.json’) >>> st == st2 True >>> os.remove(‘test.json’)

static random_cluster(composition, method='stretching', stabilization_number=20, nparal=5)

reduced2positions()

Computes the dimensional cartesian coordinates from the adimensional cell-reduced coordinates

relocate_to_cm(list_of_atoms=None)

Relocates the system of atoms to the center of mass a partial list of atoms can be used to compute the center, but all the atoms are moved to the computed center

Parameters:list_of_atoms – (list) List of atoms that will be considered for computing the center of mass by default all atoms are included

rotation(tx, ty, tz)

Rotate the molecule in the three directions

round(decimals=6, pos='reduced')

save_json(filename)

scale(tolerance=0.7)

set_cell(cell)

Set the vectors defining the cell

Parameters:cell – A matrix with the 3 unit cell vectors Returns:

set_mag_moments(mag_moments)

Set the magnetic moments with one vector on each atom

Args:

mag_moments: List or numpy array with one vector for each atom. The values will be converted into a numpy array

set_periodicity(periodicity)

Set periodicity of the structure

Args:

periodicity: (Boolean) a single value means that the structure has that

periodicity all along the 3 directions. Otherwise a list of 3 booleans is required

set_positions(positions)

Set the positions of the atoms This contains dimensional values in cartesian coordinates

Args:

positions: A array of 3 vectors with dimensional coordinates

set_reduced(reduced)

Set the reduced positions of the atoms This contains adimensional values relative to cell vectors

Parameters:reduced – Returns:

signature()

sort_axes()

Sort the lattice vectors in decremental order of their size. ‘a’ will be the longest lattice vector ‘c’ he shortest

sort_sites()

sort_sites_using_list(sorted_indices)

species

supercell(size)

Creates a supercell, replicating the positions of atoms in the x,y,z directions a number of size=(nx,ny,nz) times

to_dict

valence_electrons()

volume

Computes the volume of the cell

Return type:float Returns:float

pychemia.core.structure.cluster_minimal_distance(pos)

pychemia.core.structure.load_structure_json(filename)

pychemia.core.structure.random_structure(method, composition, periodic=True, best_volume=10000000000.0)

pychemia.core.structure.worker_star(x)