Subsystem class

The SubSystem class works as an interface for defining subsystems in hybrid simulations. Through it you can define the atoms that belong to the subsystem and the calculator that is used for it. SubSystem objects also provides special options for QM subsystems: you can setup dynamical charge calculation with enable_charge_calculation() and cell optimization with enable_cell_optimization().

You can define the atoms in the subsystem as a list of indices, with a tag or with a special string: “remaining”, which means all the atoms that are not yet assigned to a subsystem.

Full documentation of the Subsystem class

class pysic.subsystem.SubSystem(name, indices=None, tag=None, calculator=None)

Used to create and store information about a subsystem.

The end user can create and manipulate these objects when defining subsystems. The subsystems are added to the calculation by calling add_subsystem() which adds a SubSystem-object to the calculation.

When the HybridCalculator sees fit, the subsystems are materialized by converting the stored SubSystems into SubSystemInternals.

Attributes:

name: string

The unique name for this subsystem.

calculator: ASE Calculator

The calculator used.

cell_size_optimization_enabled: bool

cell_padding: float

The padding used when optimizing the cell size.

charge_calculation_enabled: bool

charge_source: string

Indicates the electron density that is used in charge calculation. Can be “pseudo” or “all-electron”.

division: string

Indicates the division algorithm used in charge caluclation. Can be “Bader” or “van Der Waals”.

gridrefinement: int

The factor by which the calculation grid is densified in charge calculation.

indices: list of ints

tag: int

enable_cell_optimization(padding)

Enable cell size optimization.

A subsystem might spatially reside in only a small portion of the entire system. DFT calculators will then waste time doing calculations in empty space, where almost none of electron density reaches.

This optimization minimizes the cell size, so that the atoms in the subsystem fit the cell with the given padding. If the padding is too small, the DFT-calculator might not work properly!

The optimization is off by default. It cannot be turned on in systems with periodic boundary conditions. The new optimized cell is always ortorhombic, regardless of the shape of the original, unoptimized cell.

Parameters:

padding: float

The minimum distance between the subsystem atoms and the cell walls.

enable_charge_calculation(division='Bader', source='all-electron', gridrefinement=4)

Enable the dynamic calculation of atom-centered charges with the specified algorithm and from the specified electron density. These charges are only used for the interaction between other subsystems.

Parameters:

division: string

Indicates the division algorithm that is used. Available options are:

• “Bader”: Bader algorithm
• “van Der Waals”: Spheres with van Der Waals radius

source: string

Indicates what type of electron density is used. Available options are:

• “pseudo”: Use the pseudo electron density provided by all ASE DFT calculators
• “all-electron”: Use the all-electron density provided by at least GPAW

gridrefinement: int

Indicates the subdivision that is used for the all-electron density. Can be other than unity only for Bader algorithm with all-electron density.

is_valid(indices, tag)

Checks that the given atom specifiers are correctly given. Does not yet check that they exist or don’t overlap with other subssystems.

set_atoms(indices=None, tag=None)

Set the atoms that belong to this subsystem. Give only one of the specifiers: indices or tag.

Parameters:

indices: list of integers or string

A list of atom indices or a special string “remaining”, which assigns all the yet unassigned atoms to this subsystem.

tag: int

The atoms with this tag belong to this subsystem.

set_calculator(calculator)

Set the calculator for the subsystem.

Parameters:

calculator: ASE compatible calculator

SubSystemInternal class

This class is meant for internal use only.

Full documentation of the SubSystemInternal class

class pysic.subsystem.SubSystemInternal(atoms, info, index_map, reverse_index_map, n_atoms)

A materialization of a SubSystem object.

This class is materialised from a SubSystem, and should not be accessible to the end user.

Attributes:

name: string

The unique name for this subsystem.

calculator: ASE Calculator

The calculator used.

cell_size_optimization_enabled: bool

cell_padding: float

charge_calculation_enabled: bool

charge_source: string

division: string

gridrefinement: int

n_atoms: int

Number of atoms in the full system.

atoms_for_interaction: ASE Atoms

The copy of subsystems atoms used in interaction calculations.

atoms_for_subsystem: ASE Atoms

The copy of subsystems atoms used in calculating subsystem energies etc.

index_map: dictionary of int to int

The keys are the atom indices in the full system, values are indices in the subssystem.

reverse_index_map: dicitonary of int to int

The keys are the atom indices in the subsystem, values are the keys in the full system.

potential_energy: float

forces: numpy array

density_grid: numpy array

Stored if spherical division is used in charge calculation.

pseudo_density: numpy array

link_atom_indices: list

timer: :class:’~pysic.utility.timer.Timer’

Used to keep track of time usage.

get_forces()

Returns a 3D numpy array that contains forces for this subsystem.

The returned array contains a row for each atom in the full system, but there is only an entry for the atoms in this subsystem. This makes it easier to calculate the total forces later on.

get_potential_energy()

Returns the potential energy contained in this subsystem.

get_pseudo_density()

Returns the electron pseudo density if available.

optimize_cell()

Tries to optimize the cell of the subsystem so only the atoms in this subsystem fit in it with the defined padding to the edges. The new cell is always ortorhombic.

update_charges()

Updates the charges in the system. Depending on the value of self.division, calls either update_charges_bader(), or update_charges_van_der_waals()

update_charges_bader()

Updates the charges in the atoms used for interaction with the Bader algorithm.

This function uses an external Bader charge calculator from http://theory.cm.utexas.edu/henkelman/code/bader/. This tool is provided also in pysic/tools. Before using this function the bader executable directory has to be added to PATH.

update_charges_van_der_waals()

Updates the atomic charges by using the electron density within a sphere of van Der Waals radius.

The charge for each atom in the system is integrated from the electron density inside the van Der Waals radius of the atom in hand. The link atoms will affect the distribution of the electron density.

update_density_grid()

Precalculates a grid of 3D points for the charge calculation with van Der Waals radius.