Output formats

This reference page described all output formats supported by the software.

Observable averages

In the integration run type, if one specifies averages_out output file, average interaval values computed in the averaging phase will be stored in this file. The averages are stored as rows of space separated values, where the first two columns are temperature and pressure and the next ones are subsequent mean observable values and the standard deviations of the mean.

If the file does not exist, it is created. In the first row, the header with names of observables' nominal values is printed (standard deviations have "d" prefix). If the file already exists, the next row is appended to it without re-outputting the header. This way, subsequent simulation runs can all print averages to the same file. For example, sample_inputs/integration.pyon input file produces the averages' output similar to

temperature pressure rho drho Z dZ 
1 0.10000000000000001 0.083816992988179809 0.00023722361014244265 1.1940170798614786 0.0033628547368692763 
1 11.5 0.93975692288822354 0.00036038372743663852 12.237385112239892 0.0046913677128219231 
1 20 1.1505099218769477 0.00036955494794587638 17.383773703103962 0.0055793772870406204

Snapshot formats

Snapshots of the system are outputted at the end of simulation runs (see Simulation pipeline, integration.output_last_snapshot). The amount of information stored (positions and orientation, box dimensions, simulation metadata) varies between the formats. The native representation is the RAMSNAP format, which contains metadata such as the number of cycles or step sizes. Currently, the following snapshot formats are supported:

Class ramsnap
Class wolfram
Class xyz

Class `ramsnap`

ramsnap(
    filename
)

Internal RAMPACK text representation of a simulation snapshot, stored to a file with the name given by the filename argument. Apart from box dimensions and particles' positions and orientations, it contains simulation metadata (which is used to resume an interrupted simulation) as key-value pairs. Format's specification is technically not a part of the public interface; thus it may change in the future (retaining the software support of older versions). Currently, it has the following structure:

[k]
[key 1] [value 1]
...
[key k] [value k]
[v11] [v21] [v31] [v12] [v22] [v32] [v13] [v23] [v33]
[N]
[r11] [r12] [r13] [O111] [O112] [O113] [O121] [O122] [O123] [O131] [O132] [O133]
...
[rN1] [rN2] [rN3] [ON11] [ON12] [ON13] [ON21] [ON22] [ON23] [ON31] [ON32] [ON33]

where:

[k]
number of key-value pairs
[vij]
j^th component of i^th box vector v_i
[N]
number of particles
[rij]
j^th component of the absolute position r_i of i^th particle
[Oijk]
j^th row and k^th column of the orientation matrix O_i of i^th particle

Metadata keys' names (depending on the context, some of the entries may not be always present):

cycles
number of full Monte Carlo cycles performed
step.[move sampler].[move]
current step size of a move [move] from a particle or box move sampler [move sampler]

Class `wolfram`

wolfram(
    filename,
    style = standard,
    **kwargs
)

Wolfram Mathematica output of the last snapshot stored to a file with the name given by the filename argument. Simulation box is not drawn.

Arguments:

style (= standard)

The style of the output. There are 2 options:

Class standard

In this format,Graphics3D contains a list of individually drawn shapes:
```
Graphics3D[{
    Sphere[position1, radius],    (* individual shape *)
    ...
    Sphere[positionN, radius]
}]
```
You can easily access the individual shapes by indexing the Graphics3D object.

Class affine_transform

The shape is drawn only once, then a list of AffineTransform-s is mapped over it:

Graphics3D[
    GeometricTransformation[
        Tube[{{0, 0, -1}, {0, 0, 1}}, radius],    (* default-oriented shape at {0, 0, 0} *)
        AffineTransform@#
    ]& /@ {
        {orientation1, position1},                (* list of positions and orientations of shapes *)
        ...
        {orientationN, positionN}
    }
]

It is the most useful for shapes, for which Wolfram Mathematica visualization code is very long, for example class generic_convex, where the whole polyhedral mesh is outputted for each shape.

**kwargs

Keyword arguments passed to shape's Wolfram printing subroutine. Please refer to shape class wolfram for available options.

NOTE: It is advisable not to open the output directly in Wolfram Mathematica, but rather copy its content into the clipboard and paste is into an empty notebook. Alternatively, the output can be loaded directly into a variable using

shapshot = ToExpression[Import[filename, "String"]]

Class `xyz`

xyz(
    filename
)

Extended XYZ snapshot stored to a file with the name given by the filename argument. Unlike standard XYZ format, which contains only positions of atoms, in the extended variant box dimensions and particle orientations are also stored. This flavor is recognized by Ovito out of the box. You can use rampack shape-preview --shape=... --output='obj(...)' (see shape-preview mode) to generate a Wavefront OBJ model of the shape and load it into Ovito, so it can render the system properly.

Extended XYZ file structure is the following

[N]
3600
Lattice="[box vectors]" Properties=species:S:1:pos:R:3:orientation:R:4 [key 1]=[value 1] ... [key k]=[value k]
A [r11] [r12] [r13] [q11] [q12] [q13] [q14]
...
A [rN1] [rN2] [rN3] [qN1] [qN2] [qN3] [qN4]

where

A
atom type; it is always A, as RAMPACK does not operate on real atoms
[N]
number of particles
[box vectors] = [v11] [v12] [v13] [v21] [v22] [v23] [v31] [v32] [v33]
where [vij] is j^th component of i^th box vector v_i
[key i]=[value i]
the same key=value pairs as in class ramsnap
[rij]
j^th component of the absolute position r_i of i^th particle
[qij]
j^th component of the rotation quaternion q_i of i^th particle

Trajectory formats

Trajectories consist of many snapshots of the system captured every X full MC cyckes. They are stored on the fly during the simulation (see Simulation pipeline, integration.record_trajectory). The native representation is RAMTRJ, which is a compact binary format. It can be later processed using the trajectory mode, for example, to calculate additional observables.

Currently, the following formats are supported:

class ramtrj
class xyz

Class `ramtrj`

ramtrj(
    filename
)

Trajectory in the internal binary RAMTRJ format stored to a file with the name given by the filename argument. It is designed to be compact with easy access to individual snapshots. It is not part of a public interface, so its format may change in the future (retaining the software support of older versions).

Currently, RAMTRJ files have the following binary structure (C language types of primitive blocks are in (...)):

[header] [snapshot 1] ... [snapshot m]

with

[header] := [magic] [version major(char)] [version minor(char)] [N(unsigned long)] [m(unsigned long)] [s(unsigned long)]
[magic] := "RAMTRJ\n" ASCII characters
[snapshot i] := [box dimensions] [particle 1] ... [particle N]
[box dimensions] := [v11(double)] [v21] [v31] [v12] [v22] [v32] [v13] [v23] [v33]
[particle i] := [ri1(double)] [ri2] [ri3] [ei1(double)] [ei2] [ei3]

where

[N]
number of particles
[m]
number of snapshots
[s]
number of cycles between two snapshots
[vij]
j^th component of i^th box vector v_i
[rij]
j^th component of the absolute position r_i of i^th particle
[eij]
j^th aircraft Euler (Tait-Brian) angle (in the extrinsic XYZ convention, in radians) of i^th particle. In the rotation matrix formalism, the net rotation matrix is R = R_zR_yR_x, where R_j is the rotation around j^th axis by [eij] angle.

The initial configuration is not stored - the first captured snapshot is for cycle number equal step size [s].

Class `xyz`

xyz(
    filename
)

Extended XYZ trajectory stored to a file with the name given by the filename argument. It is basically a collection of XYZ snapshots, so please refer to snapshot class xyz documentation. Here, each snapshot has only one auxiliary key=value pair, which is cycle=[cycle number]. This trajetory format is recognized by Ovito out of the box. You can use rampack shape-preview --shape=... --output='obj(...)' (see shape-preview mode) to generate a Wavefront OBJ model of the shape and load it into Ovito, so it can render the system properly.

Shape model formats

The shape-preview mode can export the 3D model of a shape for visualization purposes. The following formats are currently supported:

Class wolfram
Class obj

Class `wolfram`

wolfram(
    filename,
    **kwargs
)

Stores the shape model in Wolfram Mathematica format to a file with the name given by the filename argument. The output can be passed as an argument of Graphics3D object.

**kwargs are shape-specific keyword arguments tweaking visualisation options. These include:

mesh_divisions
A String with a number of subdivisions (for example "5", not 5) of the mesh. Higher numbers result in a more accurate representation, but visualisation software's performance may be hindered if the number of polygons is too high. The default value is "3". Available for: class smooth_wedge, class polyhedral_wedge, class generic_convex.

NOTE: It is advisable not to open the output directly in Wolfram Mathematica, but rather copy its content into the clipboard and paste is into an empty notebook. Alternatively, the output can be loaded directly into a variable using

shape = ToExpression[Import[filename, "String"]]

Class `obj`

obj(
    filename,
    **kwargs
)

Stores the shape model in Wavefront OBJ format to a file with the name given by the filename argument. The format is recognized by a wide range of visualization tools, including Ovito.

**kwargs are shape-specific keyword arguments tweaking visualisation options. These include:

mesh_divisions
A String with a number of subdivisions (for example "5", not 5) of the mesh. Higher numbers result in a more accurate representation, but visualisation software's performance may be hindered if the number of polygons is too high. The default value is "3". Available for all shapes.

↑ back to the top

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

output-formats.md

output-formats.md

Output formats

Contents

Observable averages

Snapshot formats

Class `ramsnap`

Class `wolfram`

Class `xyz`

Trajectory formats

Class `ramtrj`

Class `xyz`

Shape model formats

Class `wolfram`

Class `obj`

Files

output-formats.md

Latest commit

History

output-formats.md

File metadata and controls

Output formats

Contents

Observable averages

Snapshot formats

Class ramsnap

Class wolfram

Class xyz

Trajectory formats

Class ramtrj

Class xyz

Shape model formats

Class wolfram

Class obj

Class `ramsnap`

Class `wolfram`

Class `xyz`

Class `ramtrj`

Class `xyz`

Class `wolfram`

Class `obj`