ovito.io
¶
This module primarily provides two high-level functions for reading and writing external data files:
-
ovito.io.
import_file
(location, **params)¶ Imports data from an external file.
This Python function corresponds to the Load File menu command in OVITO’s user interface. The format of the imported file is automatically detected (see list of supported formats). Depending on the file’s format, additional keyword parameters may be required to specify how the data should be interpreted. These keyword parameters are documented below.
Parameters: location – The path to import. This can be a local file or a remote sftp:// URL. Returns: The new Pipeline
that has been created for the imported data.The function creates and returns a new
Pipeline
object, which uses the contents of the external data file as input. The pipeline will be wired to aFileSource
, which reads the input data from the external file and passes it on to the pipeline. You can access the data by calling thePipeline.compute()
method or, alternatively, by callingFileSource.compute()
on the datasource
. As long as the newPipeline
contains no modifiers yet, both methods returns the same data.Note that the
Pipeline
is not inserted into the three-dimensional scene. That means the loaded data won’t automatically appear in rendered images or the interactive viewports of OVITO. For that, you need to explicitly insert the pipeline into the scene by calling itsadd_to_scene()
method if desired.Furthermore, note that you can re-use the returned
Pipeline
if you want to load a different data file later on. Instead of callingimport_file()
again to load another file, you can use thepipeline.source.load(...)
method to replace the input file of the already existing pipeline.File columns
When importing XYZ files or binary LAMMPS dump files, the mapping of file columns to OVITO’s particle properties must be specified using the
columns
keyword parameter:pipeline = import_file("file.xyz", columns = ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"])
The length of the string list must match the number of data columns in the input file. See this table for standard particle property names. Alternatively, you can specify user-defined names for file colums that should be read as custom particle properties by OVITO. For vector properties, the component name must be appended to the property’s base name as demonstrated for the
Position
property in the example above. To completely ignore a file column during import, specifyNone
in thecolumns
list.For text-based LAMMPS dump files, OVITO automatically determines a reasonable column-to-property mapping, but you may override it using the
columns
keyword. This can make sense, for example, if the file columns containing the particle coordinates do not follow the standard naming schemex
,y
, andz
(e.g. when reading time-averaged atomic positions computed by LAMMPS).Frame sequences
OVITO automatically detects if the imported file contains multiple data frames (timesteps). Alternatively (and additionally), it is possible to load a sequence of files in the same directory by using the
*
wildcard character in the filename. Note that*
may appear only once, only in the filename component of the path, and only in place of numeric digits. Furthermore, it is possible to pass an explicit list of file paths to theimport_file()
function, which will be loaded as an animatable sequence. All variants can be combined. For example, to load two file sets from different directories as one consecutive sequence:import_file('sim.xyz') # Loads all frames from the given file import_file('sim.*.xyz') # Loads 'sim.0.xyz', 'sim.100.xyz', 'sim.200.xyz', etc. import_file(['sim_a.xyz', 'sim_b.xyz']) # Loads an explicit list of files import_file([ 'dir_a/sim.*.xyz', 'dir_b/sim.*.xyz']) # Loads several file sequences from different directories
The number of frames found in the input file(s) is reported by the
num_frames
attribute of the pipeline’sFileSource
You can step through the frames with afor
-loop as follows:from ovito.io import import_file # Import a sequence of files. pipeline = import_file('input/simulation.*.dump') # Loop over all frames of the sequence. for frame_index in range(pipeline.source.num_frames): # Calling FileSource.compute() loads the requested frame # from the sequence into memory and returns the data as a new # DataCollection: data = pipeline.source.compute(frame_index) # The source path and the index of the current frame # are attached as attributes to the data collection: print("Frame source:", data.attributes['SourceFile']) print("Frame index:", data.attributes['SourceFrame']) # Accessing the loaded frame data, e.g the particle positions: print(data.particles['Position'][...])
LAMMPS atom style
When loading a LAMMPS data file that is based on an atom style other than “atomic”, the style may need to be specified using the
atom_style
keyword parameter. Only the following LAMMPS atom styles are currently supported by OVITO:angle
,atomic
,body
,bond
,charge
,dipole
,full
,molecular
. LAMMPS data files generated by LAMMPS’s ownwrite_data
command contain a hint that indicates the atom style. Such files can be loaded without specifying theatom_style
keyword.Topology and trajectory files
Some simulation codes write a topology file and separate trajectory file. The former contains only static information like the bonding between atoms, the atom types, etc., which do not change during a simulation run, while the latter stores the varying data (primarily the atomic trajectories). To load such a topology-trajectory pair of files, first read the topology file with the
import_file()
function, then insert aLoadTrajectoryModifier
into the returnedPipeline
to also load the trajectory data.
-
ovito.io.
export_file
(data, file, format, **params)¶ High-level function that exports data to a file. See the Data export section for an overview of this topic.
Parameters: - data – The object to be exported. See below for options.
- file (str) – The output file path.
- format (str) – The type of file to write. See below for options.
Data to export
Various kinds of objects are accepted as data parameter by the function:
Pipeline
: Exports the data dynamically generated by a pipeline. Since pipelines can be evaluated at different animation times, multi-frame sequences can be produced from a singlePipeline
object.DataCollection
: Exports the data contained in a data collection. Data objects in the collection that are not compatible with the chosen output format are ignored. Since a data collection represents a static dataset, no frame sequences can be written.DataObject
: Exports the data object as if it were the only part of aDataCollection
.None
: All pipelines that are part of the current scene (seeovito.DataSet.scene_pipelines
) are exported. This option makes sense for scene descriptions such as the POV-Ray format.
Output format
The format parameter determines the type of file to write; the filename suffix is ignored. However, for filenames that end with
.gz
, automatic gzip compression is activated if the selected format is text-based. The following format strings are supported:"txt"
– Exporting global attributes to a text file (see below)"lammps/dump"
– LAMMPS text-based dump format"lammps/data"
– LAMMPS data format"imd"
– IMD format"vasp"
– POSCAR format"xyz"
– XYZ format"fhi-aims"
– FHI-aims format"netcdf/amber"
– Binary format for MD data following the AMBER format convention"vtk/trimesh"
– ParaView VTK format for exportingSurfaceMesh
objects"vtk/disloc"
– ParaView VTK format for exportingDislocationNetwork
objects"ca"
– Text-based format for storing dislocation lines"povray"
– POV-Ray scene format
Depending on the selected format, additional keyword arguments must be passed to
export_file()
:File columns
For the output formats lammps/dump, xyz, imd and netcdf/amber, you must specify the set of particle properties to export using the
columns
keyword parameter:export_file(pipeline, "output.xyz", "xyz", columns = ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"] )
You can export the standard particle properties and any user-defined properties present in the pipeline’s output
DataCollection
. For vector properties, the component name must be appended to the base name as demonstrated above for thePosition
property.Exporting several simulation frames
By default, only the current animation frame (frame 0 by default) is exported by the function. To export a different frame, pass the
frame
keyword parameter to theexport_file()
function. Alternatively, you can export all frames of the current animation sequence at once by passingmultiple_frames=True
. Refined control of the exported frame sequence is available through the keyword argumentsstart_frame
,end_frame
, andevery_nth_frame
.The lammps/dump and xyz file formats can store multiple frames in a single output file. For other formats, or if you intentionally want to generate one file per frame, you must pass a wildcard filename to
export_file()
. This filename must contain exactly one*
character as in the following example, which will be replaced with the animation frame number:export_file(pipeline, "output.*.dump", "lammps/dump", multiple_frames=True)
The above call is equivalent to the following
for
-loop:for i in range(pipeline.source.num_frames): export_file(pipeline, "output.%i.dump" % i, "lammps/dump", frame=i)
Floating-point formatting precision
For text-based file formats, you can set the desired formatting precision for floating-point numbers using the
precision
keyword parameter. The default output precision is 10 digits, the maximum is 17.LAMMPS atom style
When writing files in the lammps/data format, the LAMMPS atom style “atomic” is used by default. If you want to create a data file that uses a different atom style, specify it with the
atom_style
keyword parameter:export_file(pipeline, "output.data", "lammps/data", atom_tyle="bond")
The following LAMMPS atom styles are currently supported by OVITO:
angle
,atomic
,bond
,charge
,dipole
,full
,molecular
,sphere
.Global attributes
The txt file format allows you to export global quantities computed by the data pipeline to a text file. For example, to write out the number of FCC atoms identified by a
CommonNeighborAnalysisModifier
as a function of simulation time, one would use the following:export_file(pipeline, "data.txt", "txt", columns=["Timestep", "CommonNeighborAnalysis.counts.FCC"], multiple_frames=True)
See the documentation of the individual analysis modifiers to find out which global quantities they compute. You can also determine at runtime which
attributes
are available in the output data collection of aPipeline
:print(pipeline.compute().attributes)