Octopus can run in 1, 2 or 3 dimensions, depending on the value of this variable (or more, if configured with --with-max-dim=4 or higher). Note that not all input variables may be available in all cases.
Define how many directions are to be considered periodic. It has to be a number between zero and Dimensions. (WARNING: For systems that are periodic in 1D and 2D, interaction between ions is assumed to be periodic in 3D. This affects the calculation of total energy and forces.)
If XYZCoordinates, PDBCoordinates, and XSFCoordinates were not found, Octopus tries to read the coordinates for the atoms from the block Coordinates. The format is quite straightforward:
'C' | -0.56415 | 0.0 | 0.0 | no
'O' | 0.56415 | 0.0 | 0.0 | no
The first line defines a carbon atom at coordinates (-0.56415, 0.0, 0.0), that is not allowed to move during dynamical simulations. The second line has a similar meaning. This block obviously defines a carbon monoxide molecule, if the input units are eV_Angstrom. The number of coordinates for each species must be equal to the dimension of your space (generally 3). Note that in this way it is possible to fix some of the atoms (this is not possible when specifying the coordinates through a PDBCoordinates or XYZCoordinates file). The last column is optional, and the default is yes. It is always possible to fix all atoms using the MoveIons directive.
If this variable is present, the program tries to read the atomic coordinates for classical atoms. from the file specified by its value. The same as PDBCoordinates, except that the classical charge colum must be present. The interaction from the classical atoms is specified by ClassicalPotential, for QM/MM calculations. Not available in periodic systems.
If this variable is present, the program tries to read the atomic coordinates from the file specified by its value. The PDB (Protein Data Bank) format is quite complicated, and it goes well beyond the scope of this manual. You can find a comprehensive description here. From the plethora of instructions defined in the PDB standard, Octopus only reads two, ATOM and HETATOM. From these fields, it reads:
This block gives the atomic coordinates relative to the real space unit cell. The format is the same as the Coordinates block.
Note that in Octopus the origin of coordinates is in the center of the cell, so the coordinates inside the cell are in the range [-0.5, 0.5).
This block cannot be used with the minimum box shape.
Another option besides PDB and XYZ coordinates formats is XSF, as defined by the XCrySDen visualization program. Specify the filename with this variable. PeriodicDimensions will be set based on the first line (CRYSTAL, SLAB, POLYMER, or MOLECULE), and Lsize will be set based on the lattice vectors, for compatible values of BoxShape. The file should not contain ATOMS, CONVVEC, or PRIMCOORD. NOTE: The coordinates are treated in the units specified by Units and/or UnitsInput.
If an animated file is given with XSFCoordinates, this variable selects which animation step will be used. The PRIMVEC block must be written for each step.
If PDBCoordinates is not present, the program reads the atomic coordinates from the XYZ file specified by the variable XYZCoordinates -- in case this variable is present. The XYZ format is very simple: The first line of the file has an integer indicating the number of atoms. The second can contain comments that are simply ignored by Octopus. Then there follows one line per atom, containing the chemical species and the Cartesian coordinates of the atom.
WARNING: By default the coordinates are treated in the units specified by Units and/or UnitsInput, which means Octopus might expect xyz files to be in atomic units. If you want the XYZ file to be read in Angstrom, as most codes do, you can set the variable UnitsXYZFiles to angstrom.
(Experimental) This enables a new automatic method for determining the grid parameters for the pseudopotential (spacing and radius). For the moment, only the spacing can be adjusted for a few pseudopotentials.
This does not affect Octopus fixed default parameters for the standard pseudopotential set.
For some pseudopotentials, Octopus can select the grid spacing automatically so that the discretization error when calculating the total energy is below a certain threshold. This variable controls the value of that threshold. Note that other quantities of interest might require a different spacing to be considered converged within a similar threshold.
Selects the set of pseudopotentials used by default for species not defined in the Species block.
These sets of pseudopotentials come from different sources. Octopus developers have not validated them. We include them with the code for convenience of the users, but you are expected to check the quality and suitability of the pseudopotential for your application.
A species is by definition either an "ion" (nucleus + core electrons) described through a pseudopotential, or a model potential.
Note that some sets of pseudopotentials are distributed with the code. To use these pseudopotentials, you do not need to define them explicitly in the Species block, as default parameters are provided. You can select the set for default pseudopotentials using the PseudopotentialSet variable.
Additional pseudopotentials can be downloaded from the octopus homepage or from other sources. Supported norm-conserving pseudopotential formats are detected by the file extension: UPF (.upf), PSF (SIESTA, .psf), FHI (ABINIT 6, .fhi), CPI (Fritz-Haber, .cpi), QSO (quantum-simulation.org, for Qbox, .xml), HGH (Hartwigsen-Goedecker-Hutter, .hgh). PSPIO format can also be used via species_pspio if that library is linked. Note: pseudopotentials may only be used in 3D.
The format of this block is the following: The first field is a string that defines the name of the species. The second field defines the type of species (the valid options are detailed below).
Then a list of parameters follows. The parameters are specified by a first field with the parameter name and the field that follows with the value of the parameter. Some parameters are specific to a certain species while others are accepted by all species. These are mass, max_spacing, and min_radius.
These are examples of possible species:
'O' | species_pseudo | file | 'O.psf' | lmax | 1 | lloc | 1
'H' | species_pseudo | file | '../H.hgh'
'Xe' | species_pseudo | set | pseudojo_pbe_stringent
'C' | species_pseudo | file | "carbon.xml"
'jlm' | species_jellium | jellium_radius | 5.0
'rho' | species_charge_density | density_formula | "exp(-r/a)" | mass | 17.0 | valence | 6
'udf' | species_user_defined | potential_formula | "1/2*r^2" | valence | 8
'He_all' | species_full_delta
'H_all' | species_full_gaussian | gaussian_width | 0.2
'Li1D' | species_soft_coulomb | softening | 1.5 | valence | 3
The pseudopotentials may be composed of a local part, and a linear combination of nonlocal operators. These nonlocal projectors have "projector" form, \( \left| v \right> \left< v \right| \) (or, more generally speaking, \( \left| u \right> \left< v \right| \)). These projectors are localized in real space -- that is, the function \(v\) has a finite support around the nucleus. This region where the projectors are localized should be small or else the computation time required to operate with them will be very large.
In practice, this localization is fixed by requiring the definition of the projectors to be contained in a sphere of a certain radius. This radius is computed by making sure that the absolute value of the projector functions, at points outside the localization sphere, is below a certain threshold. This threshold is set by SpeciesProjectorSphereThreshold.
When this variable is set, the potential defined in the block Species is calculated and applied to the Hamiltonian at each time step. You must have at least one species_user_defined type of species to use this.
Like XYZVelocities but in PDB format, as in PDBCoordinates.
If this variable is present, Octopus will assign random velocities to the atoms following a Boltzmann distribution with temperature given by RandomVelocityTemp (in degrees Kelvin).
If XYZVelocities, PDBVelocities, and XSFVelocities are not present, Octopus will try to fetch the initial atomic velocities from this block. If this block is not present, Octopus will set the initial velocities to zero. The format of this block can be illustrated by this example:
'C' | -1.7 | 0.0 | 0.0
'O' | 1.7 | 0.0 | 0.0
It describes one carbon and one oxygen moving at the relative velocity of 3.4 velocity units.
Note: It is important for the velocities to maintain the ordering in which the atoms were defined in the coordinates specifications.
Like XYZVelocities but in XCrySDen format, as in XSFCoordinates.
Octopus will try to read the starting velocities of the atoms from the XYZ file specified by the variable XYZVelocities. Note that you do not need to specify initial velocities if you are not going to perform ion dynamics; if you are going to allow the ions to move but the velocities are not specified, they are considered to be null. Note: It is important for the velocities to maintain the ordering in which the atoms were defined in the coordinates specifications.