Back to main menu

Option: select


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


Back to main menu