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, it contains the FileSource
class, which is a data source object
that reads its input data from an external file.
-
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 automatically assigns aFileSource
to thesource
attribute of the returnedObjectNode
. The file source loads data from the external file given by thesource_path
attribute. TheObjectNode
then feeds that data 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(property='Potential Energy')) # Call FileSouce.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 contains aFileSource
.Example
The following script receives a list of simulation files on the command line. It loads them one by one and performs a common neighbor analysis to determine the number of face-centered cubic atoms in each structure:
import sys from ovito.io import * from ovito.modifiers import * node = None for file in sys.argv[1:]: if not node: # Import the first file using import_file(). # This creates the ObjectNode and sets up the modification pipeline. node = import_file(file) # Insert a modifier into the pipeline. cna = CommonNeighborAnalysisModifier() node.modifiers.append(cna) else: # To load subsequent files, call the load() function of the FileSource. node.source.load(file) # Evaluate pipeline and wait until the analysis results are available. node.compute() print("Structure %s contains %i FCC atoms." % (file, cna.counts["FCC"]))
Data access
The
FileSource
class is derived fromDataCollection
. Thus, the data loaded from the external file can be accessed as contents of theDataCollection
. The stored data represents the outcome of the last successful loading operation and may change every time a new simulation frame is loaded (seeloaded_frame
), or after a call toload()
.from ovito.io import import_file # Load a simulation file. # This creates a node with a FileSource, which also is a DataCollection. node = import_file('simulation.dump') file_source = node.source # Access particle data cached in the DataCollection. print('Simulation cell:') print(file_source.cell.matrix) print('Particle coordinates:') print(file_source.particle_properties.position.array)
-
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 stored in the
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 animation length will be automatically adjusted to match the number of frames in the file input.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.Parameters: location (str) – The local file or remote sftp:// URL to load.
-
loaded_frame
¶ The zero-based index of the frame from the input time series that is currently loaded (read-only).
-
num_frames
¶ The number of frames the loaded file or file sequence contains (read-only).
-
source_path
¶ The path or URL of the loaded file.
-
-
ovito.io.
export_file
(node, file, format, **params)¶ High-level function that exports data to a file.
Parameters: - node (
ObjectNode
) – The node that provides the data to be exported. - file (str) – The name of the output file.
- format (str) –
The type of file to write:
"fhi-aims"
– FHI-aims format"lammps_dump"
– LAMMPS text-based dump format"lammps_data"
– LAMMPS data format"imd"
– IMD format"vasp"
– POSCAR format"xyz"
– XYZ format
The function evaluates the modification pipeline of the given object node and exports the results to one or more files. By default, only the current animation frame is exported.
Depending on the selected export format, additional keyword parameters need to be specified.
File columns
When writing files in the
"lammps_dump"
,"xyz"
, orimd
formats, you must specify the particle properties to be exported using thecolumns
keyword parameter:export_file(node, "output.xyz", "xyz", columns = ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"] )
LAMMPS atom style
When writing files in the
"lammps_data"
format, the LAMMPS atom style “atomic” is used by default. If a different atom style should be used, it must be explicitly specified as a string using theatom_style
keyword parameter. The following LAMMPS atom styles are currently supported by OVITO:angle
,atomic
,body
,bond
,charge
,dipole
,full
,molecular
.- node (
-
ovito.io.
import_file
(location, **params)¶ This high-level function imports an external data file.
This Python function corresponds to the Open Local 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 the file parser to specify how the data should be interpreted. These keyword parameters are documented below.
The function creates a new
ObjectNode
and adds it to the current scene. Thus, the imported dataset will appear as an additional object in the viewports. You can remove the node from the scene again by calling itsremove_from_scene()
method.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.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. To ignore a column during import, specify
None
instead of a property name at the corresponding position in the list.Multi-timestep files
Some data formats can store multiple frames in a single file. OVITO cannot know in some cases (e.g. XYZ and LAMMPS dump) that a file contains multiple frames (because 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) print "Number of frames:", node.source.num_frames
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 as a string using the
atom_style
keyword parameter. The following LAMMPS atom styles are currently supported by OVITO:angle
,atomic
,body
,bond
,charge
,dipole
,full
,molecular
.