ovito.io
¶
This module contains functions and classes related to file input and output.
It primarily provides two high-level functions for reading and writing external files:
In addition, the module contains the FileSource
class, which is a data source for OVITO’s
data pipeline system reading its input data from an external file.
-
ovito.io.
import_file
(location, **params)¶ This high-level function imports external data from a file.
This Python function corresponds to the Load File command in OVITO’s user interface. The format of the imported file is automatically detected. However, depending on the file’s format, additional keyword parameters may need to be supplied to to specify how the data should be interpreted. These keyword parameters are documented below.
Parameters: location (str) – The file to import. This can be a local file path or a remote sftp:// URL. Returns: The ObjectNode
that has been created for the imported data.The function creates and returns a new
ObjectNode
, which provides access the imported data or allows you to apply modifiers to it.Note
Note that the newly created
ObjectNode
is not automatically inserted into the three-dimensional scene. That means it won’t appear in the interactive viewports of OVITO or in rendered images. However, you can subsequently insert the node into the scene by calling theadd_to_scene()
method on it.Sometimes it may be desirable to reuse an existing
ObjectNode
. For example if you have already set up a modification pipeline and just want to replace the input data with a different file. In this case you can callnode.source.load(...)
instead on the existingObjectNode
to select another input file while keeping the applied modifiers.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:import_file("file.xyz", columns = ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"])
The length of the list must match the number of columns in the input file. See the list of particle properties for standard property names. You can also specify a custom property name, in which case a user-defined particle property with that name is created from the corresponding file column. For vector properties, the component must be appended to the property base name as demonstrated for the
Position
property in the example above. To skip a file column during import, specifyNone
instead of a property name at the corresponding position in the columns list.For text-based LAMMPS dump files it is also possible to explicitly specify a file column mapping using the
columns
keyword. Overriding the default mapping can be useful, for example, if the file columns containing the particle positions do not have the standard namesx
,y
, andz
(e.g. when reading time-averaged atomic positions computed by LAMMPS).File sequences
You can import a sequence of files by passing a filename containing a
*
wildcard character toimport_file()
. There may be only one*
in the filename (and not in a directory name). The wildcard matches only to numbers in a filename.OVITO scans the directory and imports all matching files that belong to the sequence. Note that OVITO only loads the first file into memory though.
The length of the imported time series is reported by the
num_frames
field of theFileSource
class and is also reflected by the globalAnimationSettings
object. You can step through the frames of the animation sequence as follows:from ovito import dataset from ovito.io import import_file # Import a sequence of files. node = import_file('simulation.*.dump') # Loop over all frames of the sequence. for frame in range(node.source.num_frames): # Let the node load the corresponding file into its cache. node.compute(frame) # Access the loaded data of the current frame, print("Number of atoms at frame %i is %i." % (node.source.loaded_frame, node.source.number_of_particles))
Multi-timestep files
Some file formats can store multiple frames in a single file. OVITO cannot know in some cases (e.g. XYZ and LAMMPS dump formats) that the file contains multiple frames (because, by default, reading the entire file is avoided for performance reasons). Then it is necessary to explicitly tell OVITO to scan the entire file and load a sequence of frames by supplying the
multiple_frames
option:node = import_file("file.dump", multiple_frames = True)
You can then step through the contained frames in the same way as for sequences of files.
LAMMPS atom style
When trying to load a LAMMPS data file which is using an atom style other than “atomic”, the atom style must be explicitly specified using the
atom_style
keyword parameter. The following LAMMPS atom styles are currently supported by OVITO:angle
,atomic
,body
,bond
,charge
,dipole
,full
,molecular
.
-
ovito.io.
export_file
(node, file, format, **params)¶ High-level function that exports the results of the data pipeline to a file. See the Data export section for an overview.
Parameters: - node (
ObjectNode
) – The object node that provides the data to be exported. - file (str) – The output file path.
- format (str) –
The type of file to write:
"txt"
– A text file with global quantities computed by OVITO (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"ca"
– Text-based format for storing dislocation lines"povray"
– POV-Ray scene format
The function first evaluates the modification pipeline of the given
ObjectNode
to obtain the data to be exported. This means it is not necessary to callObjectNode.compute()
before callingexport_file()
, but it doesn’t hurt either.The
format
parameter determines the type of file written by the export function; the filename suffix is ignored. However, for files that end in.gz
, automatic gzip compression is activated if the file format is text-based.Depending on the selected format, additional keyword arguments must be provided:
File columns
When writing files in one of the formats lammps_dump, xyz, or imd, you must specify the set of particle properties to be exported using the
columns
keyword parameter:export_file(node, "output.xyz", "xyz", columns= ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"] )
See the list of standard particle properties for valid names. Additionaly, user-defined properties can be listed if they exist in the output data. For vector properties, the component name must be appended to the base name as demonstrated for the
Position
property in the example above.Exporting several simulation frames
By default, only the current animation frame (given by the
current_frame
global variable) is exported. To export a different frame, pass theframe
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 frames is possible using 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 all 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(node, "output.*.dump", "lammps_dump", multiple_frames=True)
The above call is equivalent to the following Python loop:
for i in range(node.source.num_frames): export_file(node, "output.%i.dump" % i, "lammps_dump", frame=i)
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 with a different atom style, the style can be selected using the
atom_style
keyword parameter:export_file(node, "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 OVITO’s 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 do the following:export_file(node, "data.txt", "txt", columns=["Timestep", "CommonNeighborAnalysis.counts.FCC"], multiple_frames=True)
See the documentation of each analysis modifier to find out which global quantities it computes. At runtime, you can determine which
attributes
are available for export as follows:print(node.compute().attributes)
- node (
-
class
ovito.io.
FileSource
¶ Base class: ovito.data.DataCollection
This object serves as a data source for modification pipelines and is responsible for reading the input data from one or more external files.
You normally do not create an instance of this class yourself. The
ovito.io.import_file()
function does it for you and assigns the file source to thesource
attribute of the returnedObjectNode
. This file source loads data from the external file given by thesource_path
attribute. TheObjectNode
then takes this data and feeds it into its modification pipeline.You typically don’t set the
source_path
attribute directly. Instead, use theFileSource.load()
method to load a different input file and hook it into an existing modification pipeline:from ovito.io import import_file from ovito.modifiers import ColorCodingModifier # This creates a new node with an empty modification pipeline: node = import_file('first_file.dump') # Populate the pipeline with a modifier: node.modifiers.append(ColorCodingModifier(particle_property='Potential Energy')) # Call FileSource.load() to replace the input data with a different file # but keep the node's current modification pipeline: node.source.load('second_file.dump')
File sources are also used by certain modifiers to load a reference configuration, e.g. by the
CalculateDisplacementsModifier
, whosereference
attribute also contains aFileSource
.Data access
The
FileSource
class is derived from theDataCollection
base class. This means the file source also stores the data loaded from the external file, and you can access this data through theDataCollection
base class interface. Note that the cached data represents the outcome of the most recent successful loading operation and may change every time a new simulation frame is loaded (seeloaded_frame
).from ovito.io import import_file # This creates a node with a FileSource, which also is a DataCollection. node = import_file('simulation.dump') # Access data cached in the DataCollection. print(node.source.number_of_particles) print(node.source.cell.matrix)
-
adjust_animation_interval
¶ A flag that controls whether the animation length in OVITO is automatically adjusted to match the number of frames in the loaded file or file sequence.
The current length of the animation in OVITO is managed by the global
AnimationSettings
object. The number of frames in the external file or file sequence is indicated by thenum_frames
attribute of thisFileSource
. Ifadjust_animation_interval
isTrue
, then the animation length will be automatically adjusted to match the number of frames provided by theFileSource
.In some situations it makes sense to turn this option off, for example, if you import several data files into OVITO simultaneously, but their frame counts do not match.
Default: True
-
load
(location, **params)¶ Loads a new external file into this data source object.
The function auto-detects the format of the file.
The function accepts additional keyword arguments that are forwarded to the format-specific file importer. See the documentation of the
import_file()
function for more information on this.Parameters: location (str) – The local file or remote sftp:// URL to load.
-
loaded_file
¶ The path or URL of the data file that is currently loaded and kept in memory by the
FileSource
(read-only).
-
loaded_frame
¶ The zero-based frame index that is currently loaded and kept in memory by the
FileSource
(read-only).The data of this frame is accessible through the inherited
DataCollection
interface.
-
num_frames
¶ The total number of frames the imported file or file sequence contains (read-only).
-
source_path
¶ The path or URL of the imported file or file sequence. Unlike the path return by
loaded_file
, the source path may contain a ‘*’ wildcard character when a file sequence has been imported.
-