-select all
-select invert
-select <species>
-select <index>
-select <index1>,<index2>,<index3>:<index4>,...
-select list <file>
-select random <N> <species>
-select <above|below> <d> <dir>
-select <in|out> cell
-select <in|out> box <x> <y> <z> <x'> <y'> <z'>
-select <in|out> sphere <x> <y> <z> <R>
-select <in|out> cylinder <axis> <x1> <x2> <R>
-select <in|out> cone <axis> <x> <y> <z> <α>
-select <in|out> torus <axis> <x> <y> <z> <R> <r>
-select prop <property> <value1[:value2]>
-select <NNN> <species> neighbors <index>
-select grid <file>
-select stl [center] <file>
-select <i> modulo <j>
-select [add|rm|intersect|xor|among] <any of the above>
This option allows to select atoms according to given criteria. The selection can include atoms of a given species, atoms above or below a given plane, atoms inside or outside of a geometric region, or a random set of atoms.
When using -select all the selection is cleared. All atoms will then be treated equally by other options, so this is equivalent to selecting all atoms.
When using -select invert the selection is inverted (i.e. any selected atom is un-selected, and unselected atoms are selected). If no selection was previously defined (i.e. all atoms are selected) then nothing is done since it does not make sense to select no atom.
When using -select <species>, all atoms of the given species are selected. The chemical symbol must be used (e.g. Al, Si, C, Cu...).
When using -select <index> (where <index> in an integer), only the atom of the given index is selected. Several indices can be given, separated by a comma. A range of indices can be defined by two integers separated by a colon.
When using -select list <file>, the list of atoms to select is read from a <file>. The <file> must be a text file containing one atom index (integer number) per line.
When using -select random, N atoms of the given <species> are selected randomly (where N in an integer). If N is a real number followed by the symbol "%", then the given percentage of atoms will be selected. If <species> is set to "any" or "all" then N atoms will be randomly selected regardless of their species. Note that this option attempts to generate random indices of the atoms to be selected, therefore it is largely non-reproducible, i.e. starting from the exact same system and applying the present option will likely lead to different results.
When using -select above (respectively, -select below), all atoms that are at a distance greater (repectively lesser) than the distance <d> with respect to the cartesian origin (0,0,0) along the given direction <dir> are selected. The direction <dir> can be one of "X", "Y", "Z" (referring to cartesian axes), or a crystallographic direction defined by its Miller indices [hkl], or [hkil] for hexagonal systems (see how to specify Miller indices). If the crystallographic orientation of the system is defined (e.g. through the option -properties) then the Miller indices are
considered with respect
to that orientation. Otherwise the orientation assumed is X=[100], Y=[010], Z=[001].
Using -select in (or out) allows to select atoms inside (respectively outside) of a geometric region. Only some basic geometric shapes are implemented, like the parallelepiped, sphere, and so on. The parameters depend on the geometry of the region:
When using -select in cell (or -select out cell), atoms that are inside (respectively outside) of the simulation cell are selected. No other parameter is required.
The box is a parallelepipedic box defined by two points of coordinates (x,y,z) and (x',y',z').
The sphere is defined by its center (x,y,z) and its radius R.
The cylinder is defined by its center (x1,x2) in the plane normal to the direction <axis>, and its radius R. The directions x1 and x2 are decided after the direction <axis> by permutation X, Y, Z (e.g. if <axis>=Y then x1 will be the position along the cartesian Z direction, and x2 the position along X).
The cone is defined by its main axis (X, Y or Z), the position of its tip (x, y, z), and its opening angle with respect to its axis (α in degrees).
The torus is defined by its normal axis (X, Y or Z), the position of its center (x,y, z), its main radius R, and its secondary radius r.
The positions <x>, <y>, <z> are usually given in Å. It is also possible to give them with respect to the box dimensions with the keyword BOX and an operation (see this page). Note that these keywords can only be used for positions: the radius <R> of sphere or cylinder must always be given in Å.
The option -select prop allows to select atoms whose given <property> has the given <value>. If only one value is provided then only atoms that have exactly this value for this <property> are selected. If two values are given, separated by a colon (:) then all atoms whose <property> falls in this range are selected. If "min" (or "max") is given instead of a value, then the atom(s) whose <property> has the minimum value (or the maximum value respectively) are selected.
When using -select <NNN> <species> neighbors <index>, the neighbors of the atom of the given <index> are selected. If <NNN> is a positive integer then the <NNN> closest neighbors are selected, regardless of their distance (<NNN> must then be smaller than 100). If <NNN> is a negative real number then all neighbors within a radius of |<NNN>| are selected, regardless of their number. If <NNN> is zero, then the first nearest neighbors are selected. Note that if some atoms are out of the box then the neighbor search can give wrong results (the option -wrap can be used to wrap all atoms into the box). If <species> is the chemical symbol of a species then only atoms of that species are selected. If <species> is set to "all" or "any" then atoms are selected regardless of their species.
The option -select <i> modulo <j> selects atoms that have an index equal to <i> modulo <j>, i.e. equal to i±nj where n is an integer.
When using -select grid, a finite-element grid of values is read from the <file>. The <file> must be a text file complying to one of the three following formats:
The two first formats allow to manipulate 2-D or 3-D grids; the last one only allows to generate 2-D grids (see examples below). This option can be used to select complex shapes.
When using -select stl, atoms are selected according to the 3-D shape defined in the <file>. The <file> must comply to the STL file format, either in ASCII or in binary form. This file format is widely used in 3-D printing and other 3-D applications, and can be generated by a large number of 3-D softwares, a few examples being Tinkercad, Blender, or Google Sketchup; or, models can be downloaded from a variety of sources, e.g. Cults, Pinshape, or Thingiverse. After reading the STL file, Atomsk automatically rescales the 3-D model to fit the dimensions of the atomic system, the scaling factor being equal to the smallest ratio between an atomic box dimension and the corresponding 3-D model dimension. If the keyword "center" appears before the name of the <file>, then the 3-D model is placed at the center of the atomic box. Otherwise, the 3-D model is not translated in any way. Atoms that are inside of the 3-D model are selected; to select atoms that are outside of it, simply use "-select invert". Note that, if the 3-D model contains a large number of triangles (over 100,000), the selection may take a long time to perform.
For all the cases above (except "-select all" and "-select invert"), it is possible to use one of the optional keywords "add", "rm", "intersect", or "xor", right after the keyword "-select". These keywords allow to modify a previous selection, by combining it with new criteria. Let us assume that a previous call to the option "-select" has selected a group A of atoms, and that a new call corresponds to a group B, then those keywords perform the following operations:
The other options called after the option -select will be applied only to the atoms that are selected by the present option, refer to their documentation to know how each option treats selected atoms. Beware that some options can result in strange (i.e. non-physical) results when applied to some atoms only.
Each time this option is called, a new set of atoms is selected, causing any previous selection to be lost.
Note that this option has no effect on the output: no matter which atoms are selected or not, all atoms coordinates are written in the output file(s).
By default no selection is defined, hence all atoms are selected. If a selection is defined and all selected atoms are removed (i.e. if the selection does not contain any atom anymore), then the selection is cleared, in other words the remaining atoms are all selected.
atomsk initial.cfg -select Si -rmatom select final.xyz
This will read the file initial.cfg, select all silicon atoms and remove them. The resulting system will be written to final.xyz.
atomsk initial.cfg -select 340,432,126:190,809 -rmatom select final.xyz
This will read the file initial.cfg and select the atoms number 340, 432, 126 to 190, and 809.
atomsk initial.cfg -select above 40 y -rot z 45 final.xyz
This will select atoms that have a Y coordinate greater than 40 Å. The following option -rotate will be applied only to atoms that are in this region.
atomsk initial.cfg -select above 40 [111] -cut above 30 x final.xyz
This will select atoms that are at a distance from the cartesian origin greater than 40 Å along [111] direction. The following option -cut will remove the selected atoms, but only if their X coordinate is greater than 30 Å.
atomsk initial.cfg -select in box 0 0 0 20 10 3 -shift -10 0 0 final.xyz
This will select atoms that are within the rectangular box defined by the coordinates (0,0,0) and (20,10,3). In other words all atoms which coordinates are within the ranges X=[0;20], Y=[0;10], Z=[0;3] will be selected. The following option -shift will translate all selected atoms by a vector (-10,0,0).
atomsk initial.cfg -select out box 10 20 -INF BOX-10 BOX-20 INF -fix all final.xyz
This will select atoms that are outside of the rectangular box with X coordinates between 10 Å and 10 Å before the box edge along X ("BOX-10"), the Y coordinates between 20 Å and 20 Å before the box edge along Y ("BOX-20"), and Z coordinates between -∞ and +∞. The following option -fix will be applied to all selected atoms.
atomsk initial.cfg -select out sphere 0.5*BOX 0.5*BOX 0.5*BOX 10.0 -rmatom select final.xyz
This will select atoms that are out of the sphere which center is at the center of the box, and with a radius of 10 Å. The following option -rmatom will remove the selected atoms, so that eventually only the atoms inside of the sphere remain.
atomsk initial.cfg -select out cylinder y 40 30 20 -fix all final.xyz
This will select atoms that are outside of the cylinder which axis is along Y, center is at 40 Å along Z and 30 Å along X, and which radius is 20 Å. Then these selected atoms will be fixed.
atomsk initial.cfg -select random 20 Fe -rmatom select final.xyz
This will select 20 iron atoms at random in the system. The following option -rmatom will remove atoms that are selected.
atomsk initial.cfg -select random 5% Si -substitute Si C final.xyz
This will select 5% of the silicon atoms at random. The following option will substitute the silicon atoms that are selected by carbon atoms.
atomsk initial.cfg -select random 150 any -substitute Fe C final.xyz
This will select 150 atoms at random in the system (regardless of their species). The following option will substitute the iron atoms that are selected by carbon atoms.
atomsk initial.cfg -select 6 any neighbors 9578 final.xyz
This will select the 6 nearest neighbors of atom #9578 (no matter the species of these neighbors).
atomsk initial.cfg -select 12 Si neighbors 1245 -rmatom select final.xyz
This will select the 12 nearest silicon neighbors of atom #1245, and then remove these atoms.
atomsk initial.cfg -select -8.5 any neighbors 566 final.xyz
This will select all neighbors of atom #566 within a radius of 8.5 Å.
atomsk initial.cfg -select prop vx 1e5:1e6 final.xyz
This will select all atoms whose velocity along X (vx) is between 1e5 and 1e6 (in units of velocity used in the input file).
4 4 3
# First XY plane
1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1
# Second XY plane
0 0 0 1
0 0 1 0
0 1 0 0
1 0 0 0
# Third XY plane
0 0 0 0
0 1 1 0
0 1 1 0
0 0 0 0
atomsk initial.cfg -select grid grid.txt -rmatom select final.xyz
The file "grid.txt" contains a first line defining the number of grid elements: the atomic system will be decomposed into a grid of size 4x4x3. Then, the following lines provide the status (0 or 1) of the 48 elements of the grid (note that blank spaces and empty lines are ignored). A value of 1 means that atoms inside that element will be selected, and a value of 0 that they will not. Each group of 4x4 values represent an XY plane, and there are three such groups along Z. So, Atomsk will read the file "initial.cfg", automatically scale the grid so that it matches the box dimensions, select atoms that are inside the grid elements marked "1", and remove selected atoms. The result will be written into "final.xyz".
Finite element
0.2354 0.2 0.4013540 1
0.196874 0.5354 0.541 0
0.9432587 0.651 0.3554 1
0.68354 0.2189 0.35 0
0.4568 0.2367 0.920 1
0.87413356 0.543254 0.357401 0
0.367744 0.5485 0.548 1
0.1289 0.855354 0.36871 0
0.354 0.9870 0.5688 1
0.75432 0.98700 0.10753 0
atomsk initial.cfg -select grid grid.txt -rmatom select final.xyz
The file "grid.txt" contains lines giving the position (x,y,z) of elements of a finite-element grid, followed by an integer (0 or 1). Atomsk will read the file "initial.cfg", automatically scale the grid so that it matches the box dimensions, select atoms that are inside the grid elements marked "1", and remove selected atoms. The result will be written into "final.xyz".
00000000000000
00000011000000
00001111110000
00001100110000
00001111110000
00001100110000
00000000000000
atomsk initial.cfg -select grid A.txt -rmatom select final.xyz
The file "A.txt" contains lines of 0 and 1 that form a visual representation of the letter "A". In this case the grid is 2-dimensional. Atomsk will read the file "initial.cfg", automatically scale the grid so that it matches the box dimensions, select atoms that are inside the grid elements marked "1", and remove selected atoms. The result will be written into "final.xyz".