Stable version 3.7.2 (2014-12) | 3.7.99-1 under developement (2018-01-10)

Quick links:

Input file formats↑ Return to top

Author : Luc Billard, modif. Damien Caliste

This is a description of the input formats known by V_Sim. Each format has examples of its own in the $prefix/share/doc/v_sim/examples directory after installation or in the ~/examples directory in the sources package.

Native binary format (*.d3)↑ Return to top

.d3 format has been defined by Frédéric LANÇON (frederic DOT lancon AT cea.fr).

This is a binary format tuned for Fortran output. One example can be downloaded from this site and others are available in the examples directory of the V_Sim source distribution. Read this file for a full description (still in French) of the format. In short, this is a Fortran file with the following records:

There is also a variation of this file format that can be used to store as many set of positions as desired. This is similar to the common XYZ allows to do. The description of this '-posi.d3' format can be found here.

Native plain text format (*.ascii)↑ Return to top

Definition of the box basis for ascii files

All the data are in plain text. Here is a commented example.

dxx dyx dyy dzx dzy dzz values define the box that contains the atoms. It is not necessary orthonormal. See the figure on the right to know how these values are interpreted. Since a box is explicitly given in the format, these files are considered as periodic files by V_Sim and some action are thus available, such as the translation in the box (see the user guide). When the keyword angdeg is used, the six values contains the three lengths of basis vectors in dxx dyx and dyy, and the three angles (bc, ac, ab) in dzx dzy and dzz.

After the three first mandatory lines, all subsequent lines can be comment lines (ignored), i.e. empty, containing only blanks, or beginning with ! or with #. A non comment line must contain 'x y z name', giving the 3 coordinates and the name of the atom. The coordinates of the atoms are given in the orthonormal basis not in the box basis. In case the keyword reduced has been specified, the three coordinates x, y and z are given in the box basis.

Please note that the name must contain at most 8 characters (non blank).

Please also note that real values are in free format. However, (Fortran) format like 1.03D+05 is NOT SUPPORTED and must be written 1.03E+05 (or 1.03e+05).

The keywords have been introduced in version 3.5. They can be positionned anywhere after the first three lines. The following table summurises all available keywords:

KeywordMeaningNew from
reducedAll atomic coordinates are given in reduced coordinates with respect to the box definition.3.5
angdegThe box definition contains three distances and three angles instead of the classical six projection values.3.5
bohr, bohrd0The units for the distance are Bohr.3.5
angstroem, angstroemd0The units for the distance are Angströms.3.5
atomic, atomicd0The units for the distance are Bohr.3.5
periodic, surface or freeBCThe periodicity of the system is either 3D, 2D (free direction is y) or 0D.3.5

From version 3.6, the keywords have been completed by meta data. Meta data are just additional information that does not affect directly the crystal definition given by the file. They can be positionned anywhere after the first three lines. The following table summurises all available meta data:

Meta dataMeaningNew from
qptDefine a phonon. The syntax for this keyword is qpt=[qx;qy;qz;en;...], where (qx;qy;qz) stands for the q vector of the phonon and (en) stands for its energy. Then follow (6n) values separated by ';' characters which represent the complex displacements for each atom of the system (the three real parts followed by the three imaginary parts in a cartesian basis set). A keyword line can by separated using a '\' character as last character of the line. For instance:
#metaData: qpt=[0.167;0.167;0.0000;-0.000039 \ 
#; 0.542135; 0.542135; 0.626392; 0.020661; 0.020661; 0.028839 \ 
#; 0.542506; 0.542506; 0.626965; -0.00492; -0.00492; -0.01065 \ 
#; 0.544070; 0.544077; 0.623979; 0.008137; 0.007647; 0.009051 \ 
#; 0.544077; 0.544070; 0.623979; 0.007647; 0.008137; 0.009051 \ 
#; 0.545224; 0.546040; 0.629614; -0.05386; -0.04485; -0.05695 \ 
#; 0.547737; 0.547868; 0.632119; 0.012470; 0.003422; 0.009170 \ 
# ]
The energy value is currently not used in V_Sim. The units for the phonon coordinates are given in box coordinates, including the two pi (i.e. a coordinates of 0.5 in x direction corresponds to a periodicity of two boxes in that direction. Units of displacements are not relevant since V_Sim will scale them to be visible (and thus much amplified).
3.6
diffAn array of floating point values representing node displacement between two files. It contains 3 x nNodes values in cartesian coordinates, in the unit of the file.3.6
totalEnergyThe total energy of the system, in case of an ab initio calculation output. This field is used by colourisation of paths. Posible units are 'Ry' or 'Ht'.3.6

Here is a short example for silicon:

# V_Sim ASCII format for primitive cell of silicon
  3.83959 3.83959 3.83959
  60      60      60
#keyword: angdeg, reduced
#metaData: totalEnergy=16.42378915Ht
	0.00    0.00    0.00  Si
	0.25	0.25	0.25  Si

Widely used text format (*.xyz)↑ Return to top

Common conventions

This is a common format for sharing atomic position. V_Sim supports it only for atoms positions. The format is quite free, each blank line or line beginning with a '#' is not read. Otherwise, V_Sim try to match 'string_name float_x float_y float_z' and considers that there is an atom whose name is string_name at the position (float_x, float_y, float_z). The two first lines are mandatory, the first with the number of elements and the second kept as a commentary.

One can use this format to store several configurations in one file. To do it, just append several valid blocks of two lines followed by element names and positions.

There is no box consideration thus some functionalities are disabled when this format is used. Even if internaly, V_Sim create a box around all atoms to represent them.

Special additions

In the BigDFT project, some extensions as been introduced in this format to support box, boundary conditions... V_Sim is fully compatible with these extensions:

Here is a short example of a slab made by water molecules:

3 angstroem
surface 3.0 0.0 3.0
O 1.5     0.0    1.5    
H  .7285 0.620919 1.5 
H  2.2715  0.620919 1.5 

Format for spin (*.spin)↑ Return to top

Definition of the box basis for ascii files

Here is an example (here is the associated d3 file).

This format describes spin data for a given number of atoms. Keep in mind a spin file is loaded along with a position file such as the ones described above. If the position file you're using contains 'n' atoms, then your spin file should contain at least 'n+1' lines.

1st line of a spin file is arbitrary. Then each of the following lines must match the pattern [(line_number - 1), (float_module), (float_theta), (float_phi)] where theta and phi are the classical physics spherical coordinates that set the spin orientation. Set module to 0. if you want V_Sim not to render the element. Lines after the 'n+1'-th are free for you to use.

Other formats (through plugins)↑ Return to top

All previous formats are natively supported by V_Sim. It is possible to extent this list using plug-ins. V_Sim is shipped with several official plug-ins that make the following formats available:

Configuration file format↑ Return to top

There are two configuration files. The first v_sim.res is called resources file. It is used to store all informations that have an influence on the rendering (e.g. the color, the atomic radius, the prefered pairs rendering method..). The second, v_sim.par, is called parameters file. It stores everything that is used to configure V_Sim (e.g. refresh time, gtk options...).

When V_Sim starts, these two file are looked up in the current working directory, if not found, ~/$XDG_CONFIG_HOME/v_sim is searched and finally, the installation directory. Only a resources file can be re-loaded after startup.

Resources file (v_sim.res)↑ Return to top

Here is an example. Lines beginning with a # are not parsed. Each resource is identified by a markup (a string without space, finished by ':') and followed by one or several lines of values. The valid markup are listed at the begining of the given example, and an extensive list is given here:

KeywordMeaningNew from
atomic_radius_shapeThe radius of the element and its shape, a real > 0. & [Sphere Cube Elipsoid Point]
axes_are_onControl if the axes are drawn ; boolean (0 or 1)
axes_colorDefine the color of the axes ; three floating point values (0. <= v <= 1.)
axes_label_xLabel to be drawn beside each axis ; stringversion 3.8
axes_label_yLabel to be drawn beside each axis ; stringversion 3.8
axes_label_zLabel to be drawn beside each axis ; stringversion 3.8
axes_line_stippleDot scheme detail for the lines of the axes ; 0 < integer < 2^16version 3.4
axes_line_widthDefine the width of the lines of the axes ; one floating point values (1. <= v <= 10.)
axes_positionPosition of the representation of the axes ; two floating point values (0. <= v <= 1.)version 3.7
axes_sizePortion of the screen used to draw the axis ; one floating point value (0. <= v <= 1.)version 3.8
backgroundColor_colorSet the background of the background ; four floating point values (0. <= v <= 1.)
box_colorDefine the color of the box ; three floating point values (0. <= v <= 1.)
box_is_onControl if a box is drawn around the rendering area ; boolean (0 or 1)
box_legend_positionPosition of the legend area for the box ; two floating point values (0. <= v <= 1.)version 3.7
box_line_stippleDot scheme detail for the lines of the box (main and expanded) ; 0 < 2 integers < 2^16version 3.4
box_line_widthDefine the width of the lines of the box ; one integer (1. <= v <= 10.)
box_show_lengthsPrint the box lengths ; boolean (0 or 1)version 3.6
box_side_colorRGBA color used to draw the pristine box sides when expanded ; four floating point values (0. <= v <= 1.)version 3.8
colorization_restrictInRangeApply colourisation only if in range.version 3.7
cylinder_colorTypeIt chooses the colors of the cylinders according differents criterion ;
element_colorCodes the main color in RedGreenBlueAlpha formatand the light effects on material, nine floats between 0. and 1.version 3.4
element_is_rendered (obsolete)Obsolete entry included in element_propertiesversion 3.1 | replaced by element_properties
element_propertiesDefine some properties ; rendered (0 or 1) masked(0 or 1).version 3.4
fog_color_is_specificControl if the fog uses a specific color ; boolean (0 or 1)
fog_is_onControl if the fog is used ; boolean (0 or 1)
fog_specific_colorDefine the color of the fog ; four floating point values (0. <= v <= 1.)
fog_start_endDefine the position of the fog ; two floating point values (0. <= v <= 1.)
forces_are_onControl if the forces are drawn when available ; boolean (0 or 1)version 3.7
forces_scaleScaling factor (or automatic) for the force rendering ; float (-1 for auto or a positive value)version 3.7
glExtension_renderRules the way OpenGl draws extensions (see gl_render); name (string) value (string)version 3.8
gl_renderRules the way OpenGl draws objects in general ; 4 possible strings : VISU_GL_RENDERING_WIREFRAME, VISU_GL_RENDERING_FLAT, VISU_GL_RENDERING_SMOOTH and VISU_GL_RENDERING_SMOOTH_AND_EDGEversion 3.4
highlight_radiusFactorGive the factor for the highlight radius ; one float (> 1.)version 3.6
isosurface_colorDefine the colour of one surface ; 4 floats (RGBA) 5 floats (material)version 3.4
isosurface_propertiesDefine some surface properties ; rendered (0 or 1) sensitive to planes (0 or 1)version 3.4
isosurface_property (obsolete)Properties of a given isosurfaceversion 3.3 | replaced by isosurface_color
isosurfaces_drawIntraChoose if the interior is drawn in color inverse ; a boolean (0 or 1)version 3.4
legend_is_onControl if the legend is drawn ; boolean (0 or 1)version 3.5
map_legendPositionChoose the legend position ; two floats (between 0 and 1)version 3.7
map_legendScaleChoose the scale to draw the legend for coloured maps ; float (positive)version 3.7
material (obsolete)Obsolete entry for element_colorreplaced by element_color
nodeDisplacement_arrowDescribe the arrow to be drawn ; four floats (tail lg. tail rd. head lg. head rd., negative values means auto)version 3.5
nodeDisplacement_factorChoose the factor to draw arrows in geometry differences ; float (negative means auto)version 3.5
nodeDisplacement_lblThresholdChoose the minimum value for labels in geometry differences ; float (ratio threshold if between -1 and 0)version 3.5
nodeDisplacement_minThresholdChoose the minimum value for drawn arrows in geometry differences ; float (ratio threshold if between -1 and 0)version 3.5
opengl_d_redreduced perspective distance (must be real > 1.0)
opengl_grossgross factor (must be real > 0.0)
opengl_theta_phi_omega3 real values (degrees) for user orientation with respect to sampleversion 3.1
opengl_xs_ys2 real values for image position with respect to [0.0, 1.0]x[0.0, 1.0] window
pairCylinder_linkColorTypeIt chooses the colors of the cylinders according differents criterion for each link ; [element1] [element2] [min] [max] [int id]version 3.8
pairCylinder_linkRadiusThis value is the radius for specific drawn link as cylinders ; [element1] [element2] [min] [max] [0 < real < 10]version 3.4
pairCylinder_pairRadius (obsolete)This value is the radius for specific pairs drawn as cylinders ; element1 elemen2 0 < real < 10replaced by pairCylinder_linkRadius
pairCylinder_radiusThis value is the default radius of the pairs drawn as cylinders ; 0 < real < 10version 3.1
pairWire_linkShadeFor each given pair, if positive, use a shade to colourise pairs depending on length ; "ele1" "ele2" -1 or a positive shade idversion 3.7
pairWire_linkStippleDot scheme detail for each drawn link ; "ele1" "ele2" 0 < integer < 2^16version 3.4
pairWire_linkWidthWidths detail for each drawn link ; "ele1" "ele2" 0 < integer < 10version 3.4
pairWire_pairWidth (obsolete)Widths detail for each pair drawn ; "ele1" "ele2" 0 < integer < 10replaced by pairWire_linkWidth
pairWire_widthThis value is the width for all pairs drawn ; "ele1" "ele2" 0 < integer < 10version 3.1
pair_data (obsolete)Draw pairs between [ele1] [ele2] [0. <= dmin] [0. <= dmax] [0. <= RGB <= 1.]x3replaced by pair_link
pair_linkDraw a link between [ele1] [ele2] [0. <= dmin] [0. <= dmax]version 3.4
pairs_are_onAsk the opengl engine to draw pairs between elements ; boolean 0 or 1
pairs_favoriteMethodFavorite method used to render files ; string
path_lineWidthLine width for drawing of paths ; float (positive)version 3.7
scale_definitionDefine the position, the direction, the length and the legend of a scale ; position[3] direction[3] length legendversion 3.3
scales_are_onControl if scales are drawn ; boolean (0 or 1)version 3.3
scales_colorDefine the color RGBA of all scales ; four floating point values (0. <= v <= 1.)version 3.3
scales_line_stippleDefine the stipple pattern of the lines of all scales ; one integer value (0 <= v <= 65535)version 3.4
scales_line_widthDefine the width of the lines of all scales ; one floating point value (1. <= v <= 10.)version 3.3
shade_paletteDefine a new shade by giving colours to points ; label (val [name|#rgb|#rrggbb|...], ...)version 3.7
spin_resourcesGlobal or element resource for rendering spin moduleversion 3.1

Parameters file (v_sim.par)↑ Return to top

Here is an example. t is read once at startup. Line beginning with a # are not parsed. Each parameter is identified by a markup (a string without space, finished by ':') and directly followed by its value. The valid markup are listed at the begining of the given example. A flag can be appended to the identifier to tell V_Sim if the line should be ignored depending on the way V_Sim is used (gtk flags are not read when V_Sim run as a command line tool for example). The extensive list is available below:

KeywordMeaningNew from
atomic_sphere_methodThe sphere drawing method, [GluSphere Icosahedron]version 3.4
browser_dateVisibilityShow or hide the date column in the treeview ; boolean 0 or 1version 3.5
browser_headersVisibilityShow or hide the headers in the treeview ; boolean 0 or 1version 3.5
config_autoAdjustCameraAuto adjust zoom capability for the box to be full size at zoom level 1 ; boolean 0 or 1version 3.6
config_refreshIsOnWhen on V_Sim reloads the file at periodic time ; boolean 0 or 1
config_refreshPeriod (obsolete)The period of reloading in s ; integer (0 < v <= 10)replaced by config_refreshTimeout
config_refreshTimeoutThe period of reloading in s ; integer (0 < v <= 10)version 3.8
config_showReducedCoordinatesDisplay coordinates in reduced values when picking a node ; boolean 0 or 1version 3.6
config_skinPath to a gtkrc file ; chain
config_subPanelTabViewSee or not the labels on tabs ; boolean 0 or 1
dataFile_fileExtensionThe extension used for data file ; chain e.g. '.dat'version 3.4
extension_render (obsolete)Rules the way OpenGl draws extensions (see opengl_render); name (string) value (string)version 3.4 | replaced by glExtension_render
init_scriptsScripts loaded on startup ; paths separated by ':'version 3.7
main_confirmQuitShow up a dialog to confirm when quit button is clicked ; boolean 0 or 1version 3.3
main_dockDefine the characteristic of a dock window ; visibility size(x,y) position(w,h) window_nameversion 3.3
main_panelStatusAttach a panel to a tool window ; panel_name window_name (or None or Main)version 3.3
main_resourcesPathFavorite paths to find and save the resources file ; chain[:chain]
main_unitDefine the prefered unit to display files ; stringversion 3.5
main_usePreviewAutomatically compute preview in filechooser ; booleanversion 3.4
opengl_antialiasIf true, lines are drawn smoother ; boolean 0 or 1
opengl_detailsGive a value to the quality of rendering (100 is normal) ; positive integer
opengl_immediateDrawingIf true, changes of parameters means immediate redrawing ; boolean 0 or 1
opengl_observe_methodChoose the observe method ; integer (0: constrained mode, 1: walker mode)
opengl_prefered_camera_orientationSaved prefered camera position ; three angles, two shifts, zoom and perspective levelversion 3.7
opengl_render (obsolete)Rules the way OpenGl draws objects in general ; 4 possible strings : VISU_GL_RENDERING_WIREFRAME, VISU_GL_RENDERING_FLAT, VISU_GL_RENDERING_SMOOTH and VISU_GL_RENDERING_SMOOTH_AND_EDGEreplaced by gl_render
opengl_stereoIf true, try to draw in stereo ; boolean 0 or 1version 3.4
opengl_stereoAngleGive the angle of the two receivers in stereo output ; float positiveversion 3.4
opengl_trueTransparencyIf true, the transparency rendering is enhanced ; boolean 0 or 1version 3.4
presetShadeThe id of a shade used as preset one in the shade selectors ; an integer ranging from 0version 3.5
rendering_favoriteMethodIgnored entry
scale_log_thresholdValue of the threshold used in the zero centred TOOL_MATRIX_SCALING_LOG scaling function ; a positive float (1e-3)version 3.5
wire_nonLinear (obsolete)If the color of the pairs are corrected by their length ; boolean 0 or 1replaced by wire_shade
wire_shade (obsolete)If positive, use a shade to colourise pairs depending on length ; -1 or a positive shade idversion 3.6 | replaced by pairWire_linkShade

RC file (v_sim.rc)↑ Return to top

Here is an example. This file is used by GTK to skin the application. It follows the classical Gtkrc syntax (see gtk online documentation for further explanations).

Isosurfaces data file format↑ Return to top

Author : Olivier d'Astier

Isosurfaces files (*.surf)↑ Return to top

Here is an example (here is the associated ascii file).

These files describe isosurfaces data. You can load them through the 'isosurfaces' panel. They are in utf-8 format. They have the following format:

Potential files (*.pot)↑ Return to top

It is a text file with the following format :

Instruction files (*.instruc)↑ Return to top

These are utf-8 text files with the following format :

XML data file format↑ Return to top

It is possible to save most of the selected data during an interactive session of V_Sim into a file. These data includes: planes, highlighted nodes or iso-surface definitions.

All these data have an XML format definition that can be concatenated into a single XML file:

<!ELEMENT v_sim (planes*:surfaces*:pick*:pathes*)>

Planes data file format↑ Return to top

It is possible to write a file describing planes (or tell V_Sim to export current planes). This file is an XML file. The structure is quite simple and correspond to the following DTD:

<!ELEMENT planes (plane+)>

<!ELEMENT plane (geometry:hide?:color)>
<!ATTLIST plane rendered (yes | no) "yes">

<!ELEMENT geometry EMPTY>
<!ATTLIST geometry normal-vector NMTOKENS #REQUIRED>
<!ATTLIST geometry distance NMTOKEN #REQUIRED>

<!ELEMENT hide EMPTY>
<!ATTLIST hide status (yes | no) "no">
<!ATTLIST hide invert (yes | no) "no">

<!ELEMENT color EMPTY>
<!ATTLIST color rgba NMTOKENS #REQUIRED>

Here is an example with two planes.

Surfaces data file format↑ Return to top

It is possible to write a file describing created surfaces (or tell V_Sim to export current surfaces). This file is an XML file. The structure is quite simple and correspond to the following DTD:

<!ELEMENT surfaces (surface+)>

<!ELEMENT surface (hidden-by-planes?:color?)>
<!ATTLIST surface rendered (yes | no) "yes">
<!ATTLIST surface iso-value NMTOKEN #REQUIRED>
<!ATTLIST surface name NMTOKENS>

<!ELEMENT hidden-by-planes EMPTY>
<!ATTLIST hidden-by-planes status (yes | no) "yes" #REQUIRED>

<!ELEMENT color EMPTY>
<!ATTLIST color rgba NMTOKENS>
<!ATTLIST color material NMTOKENS>

Pick data file format↑ Return to top

It is possible to write a file with the picked nodes (or tell V_Sim to export current picked ones). This file is an XML file. The structure is quite simple and correspond to the following DTD:

<!ELEMENT pick (node*|distance*|angle*)>
<!ATTLIST pick data-mode (never | selected | always) "never">
<!ATTLIST pick data-infos NMTOKEN>

<!ELEMENT node EMPTY>
<!ATTLIST node id NMTOKEN #REQUIRED>
<!ATTLIST node highlight (yes | no) "no">

<!ELEMENT distance EMPTY>
<!ATTLIST distance ref NMTOKEN #REQUIRED>
<!ATTLIST distance id NMTOKEN #REQUIRED>

<!ELEMENT angle EMPTY>
<!ATTLIST angle ref NMTOKEN #REQUIRED>
<!ATTLIST angle ref2 NMTOKEN #REQUIRED>
<!ATTLIST angle id NMTOKEN #REQUIRED>

Paths data file format↑ Return to top

It is possible to write a file with the node displacements saved as a path between several data files. This file is an XML file. The structure is quite simple and correspond to the following DTD:

<!ELEMENT pathes (path*)>
<!ATTLIST pathes translat NMTOKEN>

<!ELEMENT path (item*)>
<!ATTLIST path translat NMTOKEN>
<!ATTLIST path nodeId NMTOKEN #REQUIRED>

<!ELEMENT item EMPTY>
<!ATTLIST item time NMTOKEN #REQUIRED>
<!ATTLIST item type (dot | delta) #REQUIRED>
<!ATTLIST item coordinates NMTOKEN #REQUIRED>
<!ATTLIST item totalEnergy NMTOKEN>