# Input/output functions

## Writing to the console

The `print()` function writes a value or an object to the console (standard output on Linux/Unix). Note that this function will do nothing on Windows since there is no console.

    print("Hello world!")
    print("Result: " + x)

## Changing the working directory

The `cd()` and `pwd()` functions allow to set and query the current working directory:

    print("Current working directory is " + pwd())
    cd("/home/stuko/data/")
    print("New working directory is " + pwd())

## Loading data files

the `load()` function imports a data file into OVITO. The imported data is added as a new object to the current scene, i.e., this script function acts similar to the "Open Local File" function in OVITO's file menu. The `load()` function takes a string parameter that specifies the file or remote URL to be loaded:

    load("simulation_data.dump")	                // Load a file from the current working directory.

    load("/home/stuko/data/simulation_data.dump")	// If the file is in a different directory.

The `load()` function auto-detects the format of the file and uses the default import settings. Optionally, an object literal can be passed to the `load()` function to set additional import parameters:

    load("shear.xyz", {
    	columnMapping : ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"],
    	isMultiTimestepFile : true
    });

In the above example, `load()` is used to import an XYZ particle file containing five data columns. We have to tell the XYZ file parser which particle properties are stored in what file columns. This is done by setting the `columnMapping` parameter, which is an array of strings specifying the particle property each input column should be mapped to. In addition, the `isMultiTimestepFile` flag is set to `true` to let OVITO know that the XYZ file contains multiple timesteps.

The `load()` function returns a reference to the newly created object in the scene (a so-called scene node). You can use it to insert modifiers into the associated modification pipeline:

    node = load("simulation_data.dump")

    node.applyModifier(new SelectExpressionModifier({ expression : "PotentialEnergy < -3.9" }))
    node.applyModifier(new DeleteParticlesModifier())

## Replacing input data

Assuming that there already is an existing modification pipeline with some input file, you can change the source path to replace the input particle data with a different file. The data source of a modification pipeline can be accessed through the `source` property. The data source, in turn, has a `sourceUrl` property, which points to the external file from which the input data was read. You can either change this property to load a different file (and keep the existing modification pipeline):

    node = ovito.selectedNode
    node.source.sourceUrl = "/home/user/data/newfile.dump"

Or you can use the `load()` function of the source object to load a different file. Use this possibility if additional parameters need to be passed to the file importer, e.g.

    node.source.load("/home/user/data/newfile.dump", {
    	columnMapping: ["Particle Identifier", "Particle Type", "Position.X", "Position.Y", "Position.Z"]
    })

## Exporting data to a file

The `save()` function writes the current dataset to a file. Three alternative variants of this function exist:

    save(path, exportertype)
    save(path, exportertype, params)
    save(path, exportertype, params, node)

The path parameter specifies the name of the destination file. The exportertype parameter specifies the output format, which can be either `LAMMPSDataExporter`, `LAMMPSDumpExporter`, `XYZExporter`, `POSCARExporter`, or `IMDExporter`.

The params parameter is an object literal that specifies additional parameters to be passed to the exporter. These parameters control format-specific aspects, for example the list of particle properties and the range of animation frames to be exported:

    save("exporteddata.dump", LAMMPSDumpExporter, {
    	columnMapping: ["Position.X", "Position.Y", "Position.Z", "Structure Type"]
    })

In the above example, the `save()` function writes the current particle dataset to a LAMMPS dump file. The `columnMapping` parameter specifies the list of properties to export. The resulting output file will contain four columns with the X,Y, and Z coordinates as well as the structure types assigned to particles.

The fourth parameter, node, is optional and specifies the object to be exported if there multiple objects in the current scene. You can pass a reference returned by the `load()` function here. If you omit this parameter, the `save()` function will export the currently active object (given by `ovito.selectedNode`).