Dimensions
Section: System
Type: integer
Default: 3

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.

Interactions
Section: System
Type: block

This input option controls the interactions between systems. It basically allows to select which systems will interact with another system through a given interaction type. The format of the block is the following:


%Namespace.Interactions
  interaction_type | interaction_mode | ...
%

Here is an example to better understand how this works:


%SystemA.Interactions
  gravity | all_except | "SystemB"
%

This means that SystemA and all the systems that belong to the same namespace (i.e., all its subsystems) will interact through gravity with all interaction partners that are also able to interact through gravity, except with SystemB. Note that the opposite is not true so, although clearly unphysical, this will not prevent SystemB from feeling the gravity from SystemA (in Octopus the interactions are always one-sided).

NB: Each interaction type should only appear once in the block. Any further instances beyond the first will be ignored.

Available modes and interaction types:
Options:

• no_partners: (interaction mode) Do not interact with any partner.
• all_partners: (interaction mode) Interact with all available partners.
• only_partners: (interaction mode) Interact only with some specified partners. A list of partner names must be given.
• all_except: (interaction mode) Interact with all available partners except with some specified partners. A list of partner names to exclude must be given.
• gravity: (interaction type) Gravity interaction between two masses.
• lorenz_force: (interaction type) Lorenz force resulting from an EM field acting on a moving charge.
• coulomb_force: (interaction type) Coulomb force between two charged particles.
• linear_medium_em_field: (interaction type) Linear medium for propagation of EM fields.

PeriodicDimensions
Section: System
Type: integer
Default: 0

Define how many directions are to be considered periodic. It has to be a number between zero and Dimensions.
Options:

• 0: No direction is periodic (molecule).
• 1: The x direction is periodic.
• 2: The x and y directions are periodic.
• 3: The x, y, and z directions are periodic.

StaticExternalPotentials
Section: System
Type: block

An static external potential is a model potential added to the local potential of the Hamiltonian

The format of this block is the following: The first 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:

%ExternalPotential
   potential_user_defined | potential_formula | "1/2*r^2"
%
Options:

• file: The path for the file that describes the species.
• potential_formula: Mathematical expression that defines the potential for species_user_defined. You can use any of the x, y, z or r variables.
• density_formula: Mathematical expression that defines the charge density for species_charge_density. You can use any of the x, y, z or r variables.
• potential_user_defined: Species with user-defined potential. The potential for the species is defined by the formula given by the potential_formula parameter.
• potential_from_file: The potential is read from a file. Accepted file formats, detected by extension: obf, ncdf and csv.
• potential_charge_density: The potential for this species is created from the distribution of charge given by the density_formula parameter.

Systems
Section: System
Type: block

List of systems that will be treated in the calculation. The first column should be a string containing the system name. The second column should be the system type. See below for a list of available system types.
Options:

• electronic: An electronic system. (not fully implemented yet)
• maxwell: A maxwell system.
• classical_particle: A classical particle. Used for testing purposes only.
• charged_particle: A charged classical particle.
• dftbplus: A DFTB+ system
• linear_medium: A linear medium for classical electrodynamics.
• multisystem: A system containing other systems.

Coordinates
Section: System::Coordinates
Type: block

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:

%Coordinates
  '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.

PDBClassical
Section: System::Coordinates
Type: string

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.

PDBCoordinates
Section: System::Coordinates
Type: string

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:

• columns 13-16: The species; in fact Octopus only cares about the first letter - CA and CB will both refer to carbon - so elements whose chemical symbol has more than one letter cannot be represented in this way. So, if you want to run mercury (Hg), please use one of the other methods to input the coordinates.
• columns 18-21: The residue. Ignored.
• columns 31-54: The Cartesian coordinates. The Fortran format is (3f8.3).
• columns 61-65: Classical charge of the atom. Required if reading classical atoms, ignored otherwise. The Fortran format is (f6.2).

ReducedCoordinates
Section: System::Coordinates
Type: block

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.

XSFCoordinates
Section: System::Coordinates
Type: string

Another option besides PDB and XYZ coordinates formats is XSF, as defined by the XCrySDen visualization program. Specify the filename with this variable. The lattice vectors will also be read from this file and the value of PeriodicDimensions needs to be compatible with the first line (CRYSTAL, SLAB, POLYMER, or MOLECULE). The file should not contain ATOMS, CONVVEC, or PRIMCOORD. NOTE: The coordinates are treated in the units specified by Units and/or UnitsInput.

XSFCoordinatesAnimStep
Section: System::Coordinates
Type: integer
Default: 1

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.

XYZCoordinates
Section: System::Coordinates
Type: string

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.

PseudopotentialAutomaticParameters
Section: System::Species
Type: logical
Default: false

(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.

PseudopotentialEnergyTolerance
Section: System::Species
Type: float
Default: 0.005

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.

PseudopotentialSet
Section: System::Species
Type: integer
Default: standard

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.


Options:

• none: Do not load any pseudopotential by default. All species must be specified in the Species block.
• pseudodojo_pbe: PBE version of the pseudopotentials of http://pseudo-dojo.org. Version 0.4.
• pseudodojo_pbe_stringent: High-accuracy PBE version of the pseudopotentials of http://pseudo-dojo.org. Version 0.4.
• pseudodojo_lda: LDA pseudopotentials of http://pseudo-dojo.org. Version 0.4.
• pseudodojo_lda_stringent: High-accuracy LDA pseudopotentials of http://pseudo-dojo.org. Version 0.4.
• pseudodojo_pbesol: PBEsol version of the pseudopotentials of http://pseudo-dojo.org. Version 0.3.
• pseudodojo_pbesol_stringent: High-accuracy PBEsol version of the pseudopotentials of http://pseudo-dojo.org. Version 0.4.
• standard: The standard set of Octopus that provides LDA pseudopotentials in the PSF format for some elements: H, Li, C, N, O, Na, Si, S, Ti, Se, Cd.
• sg15: The set of Optimized Norm-Conserving Vanderbilt PBE pseudopotentials. Ref: M. Schlipf and F. Gygi, Comp. Phys. Commun. 196, 36 (2015). This set provides pseudopotentials for elements up to Z = 83 (Bi), excluding Lanthanides.
• hgh_lda_sc: The semicore set of Hartwigsen-Goedecker-Hutter LDA pseudopotentials. Ref: C. Hartwigsen, S. Goedecker, and J. Hutter, Phys. Rev. B 58, 3641 (1998).
• hgh_lda: The set of Hartwigsen-Goedecker-Hutter LDA pseudopotentials for elements from H to Rn. Ref: C. Hartwigsen, S. Goedecker, and J. Hutter, Phys. Rev. B 58, 3641 (1998).
• hscv_lda: The set of Hamann-Schlueter-Chiang-Vanderbilt (HSCV) potentials for LDA exchange and correlation downloaded from http://fpmd.ucdavis.edu/potentials/index.htm. These pseudopotentials were originally intended for the QBox code. They were generated using the method of Hamann, Schluter and Chiang. Ref: D. Vanderbilt, Phys. Rev. B 32, 8412 (1985). Warning from the original site: The potentials provided in this site are distributed without warranty. In most cases, potentials were not tested. Potentials should be thoroughly tested before being used in simulations.
• hscv_pbe: PBE version of the HSCV pseudopotentials. Check the documentation of the option hscv_lda for details and warnings.

Species
Section: System::Species
Type: block

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:

%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
%
Options:

• min_radius: The minimum radius of the box that will be used for this species.
• max_spacing: The maximum spacing allowed for converged results with this species.
• lmax: The maximum angular-momentum channel that will be used for the pseudopotential.
• lloc: The angular-momentum channel of the pseudopotential to be considered local.
• mass: The mass of the species in atomic mass units, i.e. the mass of a proton is roughly one. It is set automatically for pseudopotentials from the NIST values. For other species, the default is 1.0.
• valence: The number of electrons of the species. It is set automatically for pseudopotentials, but is mandatory for other species.
• jellium_radius: The radius of the sphere for species_jellium. If this value is not specified, the default of 0.5 bohr is used.
• gaussian_width: The width of the Gaussian (in units of spacing) used to represent the nuclear charge for species_full_gaussian. If not present, the default is 0.25.
• softening: The softening parameter a for species_soft_coulomb in units of length.
• file: The path for the file that describes the species.
• db_file: Obsolete. Use the set option of the PseudopotentialSet variable instead.
• potential_formula: Mathematical expression that defines the potential for species_user_defined. You can use any of the x, y, z or r variables.
• density_formula: Mathematical expression that defines the charge density for species_charge_density. You can use any of the x, y, z or r variables.
• thickness: The thickness of the slab for species_jellium_slab. Must be positive.
• vdw_radius: The van der Waals radius that will be used for this species.
• volume: Name of a volume block
• set: For a species_pseudo, get the pseudopotential from a particular set. This flag must be followed with one of the valid values for the variable PseudopotentialSet.
• hubbard_l: The angular-momentum for which the effective U will be applied.
• hubbard_u: The effective U that will be used for the LDA+U calculations.
• hubbard_j: The value of j (hubbard_l-1/2 or hubbard_l+1/2) on which the effective U is applied.
• hubbard_alpha: The strength of the potential constraining the occupations of the localized subspace as defined in PRB 71, 035105 (2005)
• species_pspio: (experimental) Alternative method to read pseudopotentials using the PSPIO library. This species uses the same parameters as species_pseudo.
• species_user_defined: Species with user-defined potential. The potential for the species is defined by the formula given by the potential_formula parameter. The valence parameter determines the number of electrons associated with the species. By default, a valence of 0 is assumed.
• species_full_gaussian: A full-potential atom is defined by a Gaussian accumulation of positive charge (distorted if curvilinear coordinates are used), in the form:
  
  \(q(r) = z \beta \exp[ - (\vec{r}-\vec{r_0})^2 / (\sqrt{2} \delta \sigma) ] \)
  
  \(\beta\) is chosen in order to maintain proper normalization (the integral of \(q\) should sum up to \(z\)). \(\delta\) is the grid spacing (the grid spacing in the first dimension, to be precise). \(\vec{r_0}\) is calculated in such a way that the the first moment of \(q(r)/z\) is equal to the atomic position. For a precise description, see N. A. Modine, Phys. Rev. B 55, 10289 (1997). The width of the Gaussian is set by parameter gaussian_width. The atomic number is determined from the name of the species.
• species_charge_density: The potential for this species is created from the distribution of charge given by the density_formula parameter. The valence parameter determines the number of electrons associated with the species. By default, a valence of 0 is assumed.
• species_from_file: The potential is read from a file. Accepted file formats, detected by extension: obf, ncdf and csv. The valence parameter determines the number of electrons associated with the species. By default, a valence of 0 is assumed.
• species_full_delta: Full atomic potential represented by a delta charge distribution. The atom will be displaced to the nearest grid point. The atomic number is determined from the name of the species.
• species_soft_coulomb: The potential is a soft-Coulomb function, i.e. a function in the form:
  
  \(v(r) = - z_{val} / \sqrt{a^2 + r^2}\)
  
  The value of a should be given by the mandatory softening parameter. The charge associated with this species must be given by the valence parameter.
• species_jellium_charge_density: The parameter is the name of a volume block specifying the shape of the jellium.
• species_jellium: Jellium sphere. The charge associated with this species must be given by the valence parameter.
• species_jellium_slab: A slab of jellium that extends across the simulation box in the xy-plane. The dimension along the z direction is determined by the required parameter thickness. The charge associated with this species must be given by the valence parameter.
• species_pseudo: The species is a pseudopotential. How to get the pseudopotential can be specified by the file or the set parameters. If both are missing, the pseudopotential will be taken from the PseudopotentialSet specified for the run, this is useful if you want to change some parameters of the pseudo, like the mass.
  
  The optional parameters for this type of species are lmax, that defines the maximum angular momentum component to be used, and lloc, that defines the angular momentum to be considered as local. When these parameters are not set, the value for lmax is the maximum angular component from the pseudopotential file. The default value for lloc is taken from the pseudopotential if available, if not, it is set to 0. Note that, depending on the type of pseudopotential, it might not be possible to select lmax and lloc, if that is the case the parameters will be ignored.
  
  

SpeciesProjectorSphereThreshold
Section: System::Species
Type: float
Default: 0.001

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.

SpeciesTimeDependent
Section: System::Species
Type: logical
Default: no

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.

PDBVelocities
Section: System::Velocities
Type: string

Like XYZVelocities but in PDB format, as in PDBCoordinates.

RandomVelocityTemp
Section: System::Velocities
Type: float
Default: 0.0

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). The seed for the random number generator can be modified by setting GSL_RNG_SEED environment variable.

Velocities
Section: System::Velocities
Type: block

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:

%Velocities
  '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.

XSFVelocities
Section: System::Velocities
Type: string

Like XYZVelocities but in XCrySDen format, as in XSFCoordinates.

XYZVelocities
Section: System::Velocities
Type: string

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.