Session state files

Python scripts

The export_file() function saves the output of a pipeline. To save the pipeline itself, including its data source, modifiers, parameters, and visual settings, you save the scene to an .ovito session state file. Such files can be opened with the OVITO Pro desktop application, and conversely, you can load session state files you have prepared in the desktop application into a Python script.

Saving a pipeline

The Scene.save() method writes the current scene, including all pipelines that are part of it, to a session state file. A pipeline must be added to the scene to be saved:

import ovito
from ovito.io import import_file
from ovito.modifiers import RadialDistributionFunctionModifier

pipeline = import_file("input/simulation.dump")
pipeline.modifiers.append(RadialDistributionFunctionModifier(cutoff=3.4))
pipeline.add_to_scene(name="RDF analysis")

ovito.scene.save("output/mypipeline.ovito")

The optional name argument of add_to_scene() gives the pipeline a name, which appears in the pipeline selector of OVITO Pro.

Important

A session state file stores the parameters of user-defined modifiers and other Python extensions, using Python’s pickle module, but it stores their code only if it was entered in the code editor of the OVITO Pro user interface. A modifier function that your script inserts into a pipeline, e.g. using pipeline.modifiers.append(my_function), does not get saved: after loading the session state file, the pipeline contains a Python script modifier without code, which reports an error.

Loading a pipeline

The Scene.load() method loads a session state file. Afterwards, the Scene.pipelines list contains the pipelines stored in the file:

import ovito

ovito.scene.load("output/mypipeline.ovito")
pipeline = ovito.scene.pipelines[0]
data = pipeline.compute()

You can also look up a pipeline by name:

pipeline = ovito.scene.pipelines["RDF analysis"]

Note

Python scripts can load session state files created with OVITO Pro, but not those created with OVITO Basic.

Using pipelines prepared in the desktop application

A productive way of working is to set up and fine-tune a pipeline, including the camera and the rendering settings, interactively in OVITO Pro, save it to a session state file, and then use a Python script to apply the pipeline to many input files. The script can modify the loaded pipeline before processing the files:

import ovito

pipeline = ovito.scene.pipelines[0]

# Adjust a modifier parameter of the loaded pipeline:
pipeline.modifiers[0].cutoff = 3.1

# Process a series of files with the loaded pipeline:
for path in ["input/first_file.dump", "input/second_file.dump"]:
    pipeline.source.load(path)
    data = pipeline.compute()
    rdf = data.tables["coordination-rdf"].xy()

Instead of calling load() in your script, you can let the ovitos interpreter load the session state file before it runs your script, using the -o command line option (see Preloading session state):

ovitos -o mypipeline.ovito script.py

Alternatively, the Python code generator of OVITO Pro translates a pipeline set up in the user interface into equivalent Python code, which you can then adapt. Compared to loading a session state file, this makes your script self-contained and lets you see all parameter values in the code.