Back to main menu

Option: properties

Syntax

-properties <file>

Description

This option can be used to define explicitely some properties of the system.

The <file> is a text file that must contain keywords followed by appropriate values. Empty lines, and lines starting with the hash symbol (#), are ignored. If a property is specified several times, then the last one overwrites all previous ones.

Per-atom properties are defined for each atom, e.g. the atoms energy, displacements, or velocities. If they do not modify atom positions, then they are called "auxiliary properties" (e.g. energy, velocities, electric charges...), and they are written to some file formats like CFG (see this page for more information).

System-wide properties do not apply to each atom individually but to the system as a whole, like the supercell parameters or the elastic tensor. They may affect options called afterwards and/or output files.

Below is the list of valid per-atom properties, that can be defined or applied to atoms:

• Displacement vectors can be defined using the keyword "displacement", followed by lines containing the atom index and its displacement vector u (in Å). Optionally, the displacement vector s for the shell (in the sense of an ionic core-shell model) can also be given:
  

  displacement
<id1> <ux1> <uy1> <uz1> [<sx1> <sy1> <sz1>]
<id2> <ux2> <uy2> <uz2> [<sx2> <sy2> <sz2>]
...

  The displacements can be given for all atoms, or only some of them. If shells are present, but no displacement is specified for them, then they are displaced by the same vector as their core. The displacement vectors are immediately applied to the atom positions (and shells, if any).

• Displacement functions can be defined using the keyword "displacement function", followed by three lines containing functions ux, uy, and/or uz:
  

  displacement functions
ux = <function>
uy = <function>
uz = <function>


  The functions may be composed of mathematical operators (+, -, *, /, %, ^, e, !); real or integer numbers; the keyword "pi"; the keywords Hx, Hy, Hz, which refer to box dimensions along the Cartesian X, Y, Z axes respectively; the variables x, y, z, which refer to atoms coordinates; and/or mathematical functions. The following functions are supported:

  • abs(x) Absolute value of x
  • int(x) Nearest integer to x
  • x! Factorial of integer part of x
  • sqrt(x) Square root of x
  • exp(x) Exponential of x
  • ln(x) Natural logarithm of x
  • log(x) Base-10 logarithm of x
  • cos(x) Cosinus of x (x must be in degrees)
  • sin(x) Sinus of x (x must be in degrees)
  • tan(x) Tangent of x (x must be in degrees)
  • acos(x) Arccosinus of x (x must be between -1 and 1)
  • asin(x) Arcsinus of x (x must be between -1 and 1)
  • atan(x) Arctangent of x (x must be between -1 and 1)
  • atan2(x,y) 2-arguments arctangent (x must be non-zero)

  For each atom, the functions ux, uy and uz are evaluated by substituting the variables x, y, z by the actual atom's coordinates, and the atom is immediately displaced by the computed vector. Examples of expressions are given below.

• Ionic charges can be specified using the keyword "charge" followed by lines containing the ion species and corresponding charge (the elementary charge e is usually the default unit, but Atomsk will work with whatever number is given). In case of an ionic core-shell model the charge Q of the core and the charge q of the shell can be given:
  

  charge
<species1> <Q1> [<q1>]
<species2> <Q2> [<q2>]
...

  All atoms of the <species1> will be given the charge Q₁ (and their shells the charge q₁ if defined). If charges were defined before, they are replaced by those read with this option. These charges are used for instance in the mode --edm, or to compute the electronic polarization.

• Atom types can be defined using the keyword "type":
  

  type
<species1> <type1>
<species2> <type2>
...

  This option associates each <species> with the corresponding <type>. Note that the <type> is defined as an auxiliary property for each atom, and used when writing files for programs that use "atom types" instead of atom species (e.g. LAMMPS data files or IMD files).

  For the opposite operation (i.e. replace atom types by atom species) you may want to use the option -substitute.

• Atom velocities can be defined using the keyword "velocity":
  

  velocity
<id1> <vx1> <vy1> <vz1>
<id2> <vx2> <vy2> <vz2>
...

  The velocities can be given for all atoms, or only some of them. Atoms which velocity is not given will keep their velocities if they were previously defined, or else be assigned a zero velocity. In order to generate random velocities with a Maxwell-Boltzmann distribution one can use the option -velocity.

• Any arbitrary property can be defined for each atom using the keyword "auxiliary" followed by the name of the property, each following line containing an atom index and the value of the property for that atom:
  

  auxiliary <property>
<id1> <value1>
<id2> <value2>
...

  With this, the <property> of atom <id1> takes the <value1>, and so on. Alternatively it is also possible to assign the same value to all atoms of a given species, by giving an atomic symbol instead of an atom index:

  auxiliary <property>
<species1> <value1>
<species2> <value2>
...

  This way, the <property> takes the <value1> for all atoms of the <species1>. The list can contain values for all atoms, or only for some atoms. Atoms for which no value is given will keep their value if the <property> was previously defined for them, or else will be assigned a zero value.

And here is the list of supported system-wide properties:

• Supercell parameters can be specified by using the keyword "supercell":

  supercell
H(1,1) H(1,2) H(1,3)
H(2,1) H(2,2) H(2,3)
H(3,1) H(3,2) H(3,3)


  Alternatively the conventional notation can be used with the keyword "conventional" (angles in degrees):

  conventional
a b c
α β γ

  Note that the (cartesian) coordinates of atoms are not affected, only the supercell parameters are modified.

• Current crystal orientation can be defined using the keyword "orientation" followed by Miller indices along the cartesian X, Y and Z axis (see how to specify Miller indices):

  orientation
(hkl)X
(hkl)Y
(hkl)Z

  These values do not rotate the system but define the current crystal orientation, no matter what it was before (and without verifying if it is correct or not). If the elastic tensor was defined before the crystal orientation (see below) then it is rotated to match this orientation.

• Elastic (or stiffness) tensor can be specified using the keyword "elastic" followed by the values (6x6 array) of the elastic constants in GPa:

  elastic
C11 C12 ... C16
C21 C22 ... C26
... ... ...
C61 C62 ... C66


  Alternatively, if the material is orthotropic then Voigt notation can be used by appending the keyword "Voigt" to the keyword "elastic":

  elastic Voigt
C11 C22 C33
C23 C31 C12
C44 C55 C66


  Beware: when it is read by Atomsk, the elastic tensor is always assumed to correspond to the current orientation of the system. The elastic tensor is read without taking any previous definition of the crystallographic orientation into account. In other words the C_ij' coefficients must always be provided. On the contrary if the crystal orientation is defined or changed after reading the elastic tensor, then the elastic tensor is rotated accordingly.

  Similarly, if a rotation option (such as -alignx, -rotate or -orient) is used before the elastic tensor is defined with the present option, then the elastic tensor is assumed to correspond to the rotated system. If a rotation option is called after the present option, then the elastic tensor is transformed accordingly.

  These elastic constants are used in the option -stress, and in the option -dislocation by triggering the use of anisotropic elasticity for building dislocations.

• Similarly the compliance tensor can be specified using the keyword "compliance" followed by the values (6x6 array) of the compliances in GPa^-1:

  compliance
S11 S12 ... S16
S21 S22 ... S26
... ... ...
S61 S62 ... S66


  Alternatively the Voigt notation can be used by appending the keyword "Voigt":

  compliance Voigt
S11 S22 S33
S23 S31 S12
S44 S55 S66


  The compliance tensor is immediately inverted to obtain the elastic tensor. Then the transformations of the elastic tensor explained above apply.

Default

By default none of these properties are defined.

Examples

• atomsk Fe.xsf -properties iron.txt cfg

  This will read the file Fe.xsf and read the system properties from the file iron.txt. The final result will be output to Fe.cfg.

• The example below shows how to define cell parameters:

  new_cell.txt

  #This is just a comment

#Define the new supercell vectors
#a, b, c are in Angstroms, angles in degrees
conventional
145.2 160.6 20.19
90.0 90.0 120.0


• The example below illustrates the format for defining atom charges and types. Note that two charges are specified for oxygen, so they will be interpreted as the charges of the oxygen core and shell:

  properties.txt

  #This is just a comment

#Define charges
charge
Sr 2
Ti 4
O 0.2 -2.2
#Atom types for use with LAMMPS or IMD
#Note that any number can be assigned to each species
type
Sr 2
Ti 4
O 3
Ba 1


• The example below shows how to define the property "my_energy" for some atoms. The first column is the atom index, the second column gives the value of "my_energy" for that atom. Note that it is not mandatory to give values for all atoms. Also, atom indices can appear in any order (not necessarily by increasing index).

  energy.txt

  #Per-atom energy computed with my code
auxiliary my_energy
2 -20.3
3 -20.4
4 -19.9
6 -19.86
15 -20.4
9 -19.9


• In the example below, displacement vectors are given for some atoms. The index of the atom is given, followed by the displacement along X, Y and Z (in Å). Note that these displacements are applied immediately upon reading.

  disp.txt

  #Lets displace some atoms
displacements
45 1.2 -0.4 0
67 -6.9 2.88 -10.02
191 0.5 -0.78 0.34


• In the example below, displacement functions are given. Each atom will be displaced by a vector (ux,uy,uz) that depends on its coordinates x, y and z. In this example, atoms are displaced only along z, by an amount that depends on their x and y coordinates. The keyword Hx is replaced by the length of the first box vector, and Hy by that of the second box vector. Note that these displacements are applied immediately upon reading.

  disp.txt

  # Displacements defined as functions
displacement function
ux = 0
uy = 0
uz = 10*cos(4*pi*x/Hx) + 8*sin(2*pi*y/Hy) )


• In the example file "iron.txt" below, the elastic tensor is defined first -therefore it is assumed to be the generic tensor C for the orientation X=[100], Y=[010], Z=[001]. Then the crystal orientation is given, so Atomsk will automatically rotate the elastic tensor, yielding the C' corresponding to the orientation X=[110], Y=[110], Z=[001]:

  iron.txt

  # The elastic tensor
elastic Voigt
243.30 243.30 243.30
145.00 145.00 145.00
116.10 116.10 116.10

# The crystal orientation
orientation
[110]
[1-10]
[001]


  This is often the most convenient way to obtain an elastic tensor suitable for your system.

• Now in the example below, the crystal orientation is defined first, therefore the provided elastic tensor must be the rotated C' for that orientation -remember that when Atomsk reads the elastic tensor it always assumes that it corresponds to the current orientation of the system:

  iron.txt

  # The crystal orientation
orientation
[1_1_0]
[1_-1_0]
[0_0_1]

# The elastic tensor
elastic
243 72.5 145 72.5 0.0 0.0
72.5 60.8 97.1 60.8 0.0 0.0
145 97.1 310 155 0.0 0.0
72.5 60.8 155 89.8 0.0 0.0
0.0 0.0 0.0 0.0 116 58.0
0.0 0.0 0.0 0.0 58.0 58.0


Back to main menu