ovito.io — OVITO Python Reference 3.15.3-dev-HEAD-b1e9512d documentation

# `ovito.io`

This module provides two high-level functions for reading and writing data files:

> - `import_file()`

> - `export_file()`

Furthermore, it contains the base class for custom file readers and file writers:

> - `FileReaderInterface`

> - `FileWriterInterface`

class ovito.io.FileReaderInterface

  Base: `traits.has_traits.HasTraits`

  Abstract base class for Python-based file readers.

  When deriving from this class, you must implement the methods `detect()` and `parse()`. Implementing the `scan()` method is only necessary for file formats that can store more than one trajectory frame per file.

  Added in version 3.9.0.

  abstract detect(filename)

    This method is called by the system to let the file reader inspect the given file and determine whether it is in a format that can be read by the class’ `parse()` method.

    For best performance, your implementation of this method should try to determine as efficiently as possible whether the given file uses a supported format by reading and inspecting just the file’s header – not the entire file.

    Parameters:

      filename (str) – The local filesystem path of the input file.

    Returns:

      `True` if this file reader would like to load the given file. The system will invoke `scan()` or `parse()` next. `False` if this class cannot handle the file’s format.

    Return type:

      bool

  abstract parse(data, *, filename, url, frame_index, frame_info, is_new_file, **kwargs)

    The main work function, which is called by OVITO to have the file reader parse a dataset or one trajectory frame from the given file.

    Parameters:

      - data (DataCollection) – Container in which the file reader should store any data it loads from the file.

      - filename (str) – The local filesystem path the system is requesting to load.

      - url (str) – The URL the file originally came from. This may be a remote location (e.g. https:// or sftp:// URL). In any case, the file reader should use filename to access the local copy of the file.

      - frame_index (int) – The zero-based index of the frame to load from the trajectory.

      - frame_info (Any) – If the input file contains multiple trajectory frames, this argument is the parser-specific indexing information obtained by your `scan()` method implementation, helping `parse()` seek to the requested frame in the file (e.g. a byte offset or line number).

      - is_new_file (bool) – Indicates that the user newly opened this trajectory in the OVITO application and the file reader should discard any existing objects in the data collection (e.g. leftovers from another file reader). Will be `True` only during the first call to `parse()` after your file reader was newly associated with a `FileSource`.

      - kwargs (Any) – Any further arguments that may be passed in by the system. This parameter should always be part of the function signature for forward compatibility with future versions of OVITO, which may provide additional keyword arguments.

  abstract scan(filename, register_frame)

    Optional method called by the system to let the file reader discover and index the trajectory frames stored in the given file. Only file readers for formats that allow storing multiple frames per file need to implement this method.

    Parameters:

      - filename (str) – The local filesystem path of the input file to scan.

      - register_frame (Callable[[Any, str | None], None]) – A callback function provided by the system, which must be called exactly once for every trajectory frame found in the input file during the scan process.

    The register_frame() callback function has the following signature:

        register_frame(frame_info: Any = None, label: Optional[int|float|str] = None)

    The frame_info value and the label describe one trajectory frame discovered by your scan method and the system stores the information until later when `parse()` is invoked by the system to request loading of an individual frame. Then the frame_info value will be available for the file reader to quickly seek to the requested frame in the input file and load its contents.

    The label parameter can optionally be specified to identify each frame in a human-readable way. The labels will be displayed in the timeline of OVITO. An integer label typically denotes a simulation timestep number, a floating-point value a physical simulation time, and a string can be used to label the loaded configurations with arbitrary texts.

    See Example FR1: Custom file reader loading particle properties and the simulation cell for a simple implementation of the `scan()` method. See Example FR2: Optimizing the performance of Example FR1 for a well-behaved implementation yielding best performance.

class ovito.io.FileWriterInterface

  Base: `traits.has_traits.HasTraits`

  Abstract base class for Python-based file writers. To implement a custom file writer for OVITO, derive from this class and implement the `write()` method. Furthermore, the class provides a number of methods that can be overridden to specify the behavior of the file writer.

  Code example:

      from ovito.data import Particles
      from ovito.io import FileWriterInterface
      from ovito.pipeline import Pipeline
      from typing import Any, Sequence

      class ParticleCountsWriter(FileWriterInterface):
          "Writes the number of particles in the system for each trajectory frame to a text file."

          def supports_trajectories(self):
              return True

          def exportable_type(self):
              return Particles

          def write(self, *, filename: str, frames: Sequence[int], pipeline: Pipeline, **kwargs: Any):
              with open(filename, 'w') as file:
                  for progress, frame in enumerate(frames):
                      yield progress / len(frames)
                      data = pipeline.compute(frame)
                      file.write(f"{data.particles.count} particles at frame {frame}\n")

  Then perform the trajectory export by calling the `export_file()` function as follows:

      export_file(pipeline, "output/particle_counts.txt", format=ParticleCountsWriter, multiple_frames=True)

  Added in version 3.12.0.

  exportable_type()

    This method can be overridden by a derived class to indicate the type of data that the file writer is able to export.

    The method should return a `DataObject`-derived class if this file writer is designed to export a single data object, for example `ovito.data.Particles` or `ovito.data.DataTable`. This will give the user the option to select a data object of the right type from the pipeline’s data collection in the OVITO Pro GUI or by passing the key argument to the `export_file()` function. The selected data object will be passed to the `write()` method as the object_ref parameter.

        from ovito.io import FileWriterInterface
        from ovito.data import DataObject, DataTable
        from ovito.pipeline import Pipeline
        import numpy

        class ClusterSizesWriter(FileWriterInterface):
            """ Writes the list of cluster sizes to a NumPy file, which were computed by a
                ClusterAnalysisModifier and stored in the DataTable named 'clusters' """

            def exportable_type(self):
                return DataTable

            def write(self, *, filename: str, frame: int, pipeline: Pipeline, object_ref: DataObject.Ref, **kwargs):
                data = pipeline.compute(frame)
                table = data.get(object_ref)
                numpy.save(filename, table['Cluster Size'])

        pipeline.modifiers.append(ClusterAnalysisModifier(cutoff=3.0, sort_by_size=True))
        export_file(pipeline, "output/cluster_sizes.npy", format=ClusterSizesWriter, key='clusters')

    If the file writer doesn’t want to give the user a choice regarding the exported data object, it should return the `Pipeline` class to indicate that the `write()` method is going to automatically pick one or more data objects from the pipeline’s output `DataCollection` to export. This is the default behavior:

        def exportable_type(self):
            return ovito.pipeline.Pipeline

    Return type:

      Type[Pipeline] | Type[DataObject]

  supports_trajectories()

    This method can be overridden by a derived class to indicate whether the file writer supports exporting entire trajectories to a single file:

        def supports_trajectories(self):
            return True

    If the method returns `True`, the file writer may be invoked by OVITO to export a sequence of animation frames to a single output file in one go. If not implemented or if the method returns `False`, the system assumes that the writer can only export single configurations (one frame per file).

    Return type:

      bool

  abstract write(*, filename, frames, frame, pipeline=None, object_ref=DataObject.Ref(), **kwargs)

    Main work function, which is called by OVITO to have the file writer produce an output file. The method must be implemented by the derived class.

    If the file writer supports exporting trajectories, as indicated by the `supports_trajectories()` method, then the `write()` method is invoked only once to export a sequence of animation frames to a single file. The method should then iterate over all frames specified by the frames parameter and write them to the destination file.

    If the user selected to export only a single frame, or if the user selected to export the trajectory to a sequence of separate files, then the method is invoked once per frame, each time with a different destination filename.

    All parameters are keyword-only arguments. Parameters the function is not interested in may go into the kwargs dictionary.

    Parameters:

      - filename (str) – The local filesystem path the data should be written to. The file writer should create a new file or overwrite an existing file at this location.

      - frames (Sequence[int]) – A sequence of 0-based frame numbers that should be written to the file. The sequence may contain a single frame index, if the file writer is invoked to write a single static frame.

      - frame (int | None) – The 0-based index of the frame to write to the file. This parameter is only set when the file writer is invoked to write a single frame.

      - pipeline (Pipeline | None) – The pipeline object that produces the data to be written to the file. The file writer should obtain the data using a call to `Pipeline.compute`.

      - object_ref (Ref) – A reference to the data object in the pipeline’s `DataCollection` the file writer should export. The file writer may obtain the specified data object by calling `DataCollection.get`.

      - kwargs (Any) – Any further arguments that may be passed in by the system. This parameter should always be part of the function signature for forward compatibility with future versions of OVITO, which may provide additional keyword arguments.

ovito.io.export_file(data, file, format, **params)

  Writes data to an output file. See section Data export for an overview.

  Parameters:

    - data (Pipeline | DataCollection | DataObject | None) – The object to be exported. See available options below.

    - file (str | PathLike) – The output file path.

    - format (str | Type[FileWriterInterface]) – The kind of file to write. See available options below.

    - params (Any) – Optional keyword arguments depending on the selected format.

  Exportable objects

  The following kinds of Python objects can be passed to this function:

  `Pipeline`

    If you provide a data pipeline, the dynamically computed output of the pipeline gets exported. Since pipelines support evaluation at different animation times, a sequence of frames can be exported by passing the extra keyword argument `multiple_frames=True`, see below.

  `DataCollection`

    If you provide a data collection, the static snapshot stored in the collection is exported. Note that it depends on the selected file format which objects from the data collection will be exported - or you may have to provide extra function arguments to specify which data object(s) to export.

  `DataObject`

    If you provide a single data object, e.g. a `DataTable` or `SurfaceMesh`, just that one object gets exported. The behavior is similar to providing a `DataCollection` containing a single data object.

  None

    This exports the entire visualization scene, i.e. the output of all data pipelines in the current scene (see `ovito.Scene.pipelines` list). This option is currently supported only by the glTF and POV-Ray exporters, which generate a full scene description file.

  Additional keyword parameters, as documented below, let you control which aspects of a dataset will be written to the output file. For instance, for some file formats the `columns` keyword controls the set of particle properties to be exported.

  Output filename

  The parameter file specifies the path of the output file. If the filename ends with the suffix .gz, the output file will be compressed using the zlib library to save disk space (works only for text-based file formats).

  If a wildcard “*” character appears in the filename, then one file per animation frame is written and the “*” character is replaced with the frame number. This feature is typically used in conjunction with the `multiple_frames=True` option, see below.

  Output formats

  The parameter format may be one of the following strings selecting the kind of file to write (list of supported file formats):

  Format string | Description
  --- | ---
  `"txt/attr"` | Export global attributes to a text file (see below)
  `"txt/table"` | Export tabular data of a `DataTable` or other `PropertyContainer` to a text file
  `"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
  `"gsd/hoomd"` | GSD format used by the HOOMD-blue simulation code
  `"netcdf/amber"` | Binary format for MD data following the AMBER format convention
  `"vtk/trimesh"` | ParaView VTK format for exporting `SurfaceMesh` objects
  `"vtk/disloc"` | ParaView VTK format for exporting `DislocationNetwork` objects
  `"vtk/grid"` | ParaView VTK format for exporting `VoxelGrid` objects
  `"ca"` | Text-based format for storing dislocation lines
  `"gltf"` | glTF 3d scene format (.glb file extension) - See glTF file exporter
  `"povray"` | POV-Ray scene format
  `"ase/traj"` | ASE trajectory file format - See ASE trajectory writer

  Alternatively, format may be a Python class derived from `FileWriterInterface` that implements a custom file writer. Depending on the selected output format, additional keyword arguments may be passed to `export_file()` as documented in the following sections.

  File columns

  For output formats lammps/dump, xyz, imd, and netcdf/amber you must specify the list of particle properties to be exported by providing the `columns` keyword argument:

      export_file(pipeline, "output.xyz", "xyz", columns =
        ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"])

  When exporting a vectorial property, you can specify a particular vector component by appending it as a suffix to the base name, e.g. `"Position.Z"` or `"Atomic Strain.XY"` (see `Property.component_names`). If you do not specify a component, all components of the vector property will be exported in the form of several consecutive data columns (since OVITO 3.8).

  Tip

  If you are not sure which particle properties are available for export, you can print the list of particle properties to the console as follows:

      print(pipeline.compute().particles)

  Exporting several simulation frames

  By default, only the current animation frame (frame 0 by default) is exported. To export a different trajectory frame, pass the `frame` keyword parameter to the `export_file()` function. Alternatively, you can export all frames of the animation sequence at once by specifying `multiple_frames=True`. More refined control is possible through the keyword arguments `start_frame`, `end_frame`, and `every_nth_frame`.

  Some file formats such as lammps/dump, xyz, gsd/hoomd or netcdf/amber can store all frames of the exported trajectory in a single output file. For other formats, or if you prefer one file per frame, you must pass a filename pattern to `export_file()`. The specified output filename must contain a `*` wildcard character as in the following example, which will be replaced with the animation frame number during export:

      export_file(pipeline, "output.*.dump", "lammps/dump", multiple_frames=True)

  This is equivalent to an explicit for-loop that exports the frames one by one to a series of files:

      for i in range(pipeline.num_frames):
          export_file(pipeline, f"output.{i}.dump", "lammps/dump", frame=i)

  Floating-point number precision

  For text-based file formats, you can specify the desired formatting precision for floating-point values using the `precision` keyword parameter. The default output precision is 10 digits; the maximum is 17. For the GSD format, the precision of floating-point values can be set to either 32 or 64 bits using the `dtype` keyword parameter (see GSD/HOOMD file exporter for details).

  LAMMPS atom style

  When writing files in the lammps/data format, the LAMMPS atom style “atomic” is used by default. To generate a data file with a different LAMMPS atom style, specify it using the `atom_style` keyword parameter:

      export_file(pipeline, "output.data", "lammps/data", atom_style="bond")
      export_file(pipeline, "output.data", "lammps/data", atom_style="hybrid", atom_substyles=("template", "charge"))

  If at least one `ParticleType` of the exported model has a non-zero `mass` value, OVITO writes a `Masses` section to the LAMMPS data file. You can suppress it by passing `omit_masses=True` to the export function.

  The option `ignore_identifiers=True` replaces any existing atom IDs (particle property Particle Identifier) with a new contiguous sequence of numeric IDs during export. The option `consecutive_type_ids=True` replaces existing numeric type IDs of particle/bond/angle/dihedral/improper types with new values during export. The option `export_type_names=True` writes the names of OVITO particle/bond/angle/dihedral/improper types to the data file as LAMMPS type maps.

  LAMMPS triclinic simulation cell format

  Added in version 3.10.6.

  OVITO can export lammps/dump and lammps/data files using either the restricted or the new general triclinic format. The option can be toggled using the `restricted_triclinic` keyword parameter. Currently this option defaults to `True`, maintaining backward compatibility with previous versions of OVITO and LAMMPS.

  VASP (POSCAR) format

  When exporting to the vasp file format, OVITO will output atomic positions and velocities in Cartesian coordinates by default. You can request output in reduced cell coordinates by specifying the `reduced` keyword parameter:

      export_file(pipeline, "structure.poscar", "vasp", reduced=True)

  Global attributes

  The txt/attr file format allows you to write global quantities computed by the data pipeline to a text file. For example, here is how you export the number of FCC atoms identified by a `CommonNeighborAnalysisModifier` as a function of simulation time to a simple text file:

      export_file(pipeline, "data.txt", "txt/attr",
          columns=["Timestep", "CommonNeighborAnalysis.counts.FCC"],
          multiple_frames=True)

  Tip

  If you are not sure which global attributes are available for export, you can print the list of `attributes` produced by your current data pipeline to the console:

      print(pipeline.compute().attributes)

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 - including registered user-defined file readers). 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 (str | PathLike | Sequence[str]) – The file(s) to import. This can be a local file path or a remote sftp:// or https:// URL (see below).

    - params (Any) – Additional keyword parameters to be passed to the file reader. See below and the documentation of individual file readers for format-specific options.

  Returns:

    A newly created pipeline for loading the data from disk.

  Return type:

    Pipeline

  The function creates and returns a new `Pipeline` object, which uses the contents of the external file as input. The pipeline will be wired to a `FileSource`, which reads the input simulation data from the external file and passes it on to the pipeline. You can access the unmodified input data by calling `compute()` on the pipeline’s `source` node.

  Note that the `Pipeline` is not automatically inserted into the three-dimensional `scene`. That means the loaded data won’t appear in rendered images or the interactive viewports of OVITO by default. For that to happen, you need to explicitly insert the pipeline into the scene by calling its `add_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 calling `import_file()` again to load another file, you can use the `pipeline.source.load(...)` method to replace the input file of the already existing pipeline.

  File data columns

  When importing simple-format XYZ files or legacy binary LAMMPS dump files, the mapping of file columns to particle properties in OVITO 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 number of column strings must match the actual 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 columns 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 ignore a file column during import, use `None` as entry in the `columns` list.

  For LAMMPS dump files or extended-format XYZ 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 scheme `x`, `y`, and `z` (as is the case when importing time-averaged atomic positions computed by LAMMPS, for example).

  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 the `import_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')     # Load all frames contained in the given file
      import_file('sim.*.xyz')   # Load 'sim.0.xyz', 'sim.100.xyz', 'sim.200.xyz', etc.
      import_file(['sim_a.xyz', 'sim_b.xyz'])  # Load an explicit list of snapshot files
      import_file(['dir_a/sim.*.xyz',
                   'dir_b/sim.*.xyz']) # Load 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’s `FileSource` You can step through the frames with a `for`-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.
      # The iterator calls compute() on the FileSource to load each frame into memory
      # and return the data as a new DataCollection:
      for data in pipeline.frames:

          # 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.positions[...])

  LAMMPS atom style

  When loading a LAMMPS data file, the atom style may have to be specified using the `atom_style` keyword parameter unless the file contains a hint string, which allows OVITO to detect the style automatically. Data files written by the LAMMPS `write_data` command or by OVITO contain such a hint, for example. For data files not containing a hint, the atom style must be specified explicitly as in these examples:

      import_file('full_model.data', atom_style = 'full')
      import_file('hybrid_model.data', atom_style = 'hybrid', atom_substyles = ('template', 'charge'))

  Particle ordering

  Particles are read and stored by OVITO in the same order as they are listed in the input file. Some file formats contain unique particle identifiers or tags which allow OVITO to track individual particles over time even if the storage order changes from frame to frame. OVITO will automatically make use of that information where appropriate without touching the original storage order. However, in some situations it may be desirable to explicitly have the particles sorted with respect to the IDs. You can request this reordering by passing the `sort_particles=True` option to `import_file()`. Note that this option is without effect if the input file contains no particle identifiers.

  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 a `LoadTrajectoryModifier` into the returned `Pipeline` to also load the trajectory data.

  Remote file access via SSH and HTTPS

  Some builds of the OVITO Python module support loading files from remote servers via the SSH File Transfer Protocol (SFTP) or HTTPS protocol. To load a file from a remote server, specify the file’s URL in the form `sftp://username@host/path/to/file` or `https://host/path/to/file`. If necessary, the user will be prompted for the password to access the remote server. Alternatively, the password can be provided as part of the URL (separated by a colon after the username). On some platforms, two different SSH connection methods are supported by OVITO: the built-in SSH client implementation (libssh) and the external OpenSSH client program, which is available on many systems. You can select the desired SSH client implementation by setting the environment variable `OVITO_SSH_METHOD` to either “libssh” or “openssh”. The environment variable `OVITO_SSH_LOG=1` can be useful to debug connection problems.

  Explicit file format specification

  Normally, OVITO detects the format of the imported file(s) automatically. In rare cases, however, the auto-detection mechanism may fail. Then you can explicitly specify the file format using the optional `input_format` keyword parameter. It must one of the following supported format identifiers: `"ca"`, `"castep/cell"`, `"castep/md"`, `"cfg"`, `"cif"`, `"dcd"`, `"dlpoly"`, `"fhi-aims"`, `"fhi-aims/log"`, `"galamost"`, `"gaussian/cube"`, `"gro"`, `"gsd/hoomd"`, `"imd"`, `"lammps/data"`, `"lammps/dump"`, `"lammps/dump/bin"`, `"lammps/dump/grid"`, `"lammps/dump/local"`, `"lammps/dump/yaml"`, `"mercurydpm"`, `"mmcif"`, `"mol/sdf"`, `"netcdf/amber"`, `"obj"`, `"oxdna"`, `"parcas"`, `"pdb"`, `"quantumespresso"`, `"reaxff/bonds"`, `"stl"`, `"vasp"`, `"vtk/legacy/mesh"`, `"vtk/pvd"`, `"vtk/vti/grid"`, `"vtk/vtm"`, `"vtk/vtp/mesh"`, `"vtk/vtp/particles"`, `"vtk/vts/grid"`, `"xsf"`, `"xtc"`, `"xyz"`. Alternatively, `input_format` may specify a `FileReaderInterface` class or object.

  See also

  - ASE database reader

  - ASE trajectory reader

  - CFG (AtomEye) file reader

  - Gaussian Cube file reader

  - Gromacs GRO file reader

  - Gromacs XTC file reader

  - GSD/HOOMD file reader

  - LAMMPS data file reader

  - LAMMPS dump file reader

  - LAMMPS dump grid file reader

  - LAMMPS dump local file reader

  - PDB file reader

  - POSCAR / XDATCAR / CHGCAR file reader

  - ReaxFF file reader

  - XYZ file reader