# Example M1: Calculating mean square displacement

This example presents a user-defined modifier function for calculating the mean square displacement (MSD) for a system of moving particles. OVITO provides the built-in Displacement Vectors modifier, which calculates the individual displacement of each particle. It stores its results in the `"Displacement Magnitude"` particle property. So all our user-defined modifier function needs to do is to sum up the squared displacement magnitudes and divide by the number of particles:

    import numpy

    def modify(frame, data):
        # Access the per-particle displacement magnitudes computed by the
        # 'Displacement Vectors' modifier preceding this user-defined modifier in the
        # data pipeline:
        displacement_magnitudes = data.particles['Displacement Magnitude']

        # Compute MSD:
        msd = numpy.sum(displacement_magnitudes ** 2) / len(displacement_magnitudes)

        # Output value as a global attribute to make it available within OVITO:
        data.attributes["MSD"] = msd

When used within the graphical program, the MSD value computed by this custom modifier may be exported to a text file as a function of simulation time using OVITO’s standard file export feature (Select `Table of Values` as output format).

Alternatively, we can make use of the custom modifier function from within a non-interactive batch script, which is run with the `ovitos` interpreter. Then we have to insert the `CalculateDisplacementsModifier` programmatically:

    from ovito.io import import_file, export_file
    from ovito.modifiers import CalculateDisplacementsModifier
    import numpy

    # Load input data and create a data pipeline.
    pipeline = import_file("input/simulation.dump")

    # Calculate per-particle displacements with respect to initial simulation frame:
    pipeline.modifiers.append(CalculateDisplacementsModifier())

    # Define the custom modifier function:
    def calculate_msd(frame, data):

        # Access the per-particle displacement magnitudes computed by the
        # CalculateDisplacementsModifier that precedes this user-defined modifier in the
        # data pipeline:
        displacement_magnitudes = data.particles['Displacement Magnitude']

        # Compute MSD:
        msd = numpy.sum(displacement_magnitudes ** 2) / len(displacement_magnitudes)

        # Output MSD value as a global attribute:
        data.attributes["MSD"] = msd

    # Insert user-defined modifier function into the data pipeline.
    pipeline.modifiers.append(calculate_msd)

    # Export calculated MSD value to a text file and let OVITO's data pipeline do the rest:
    export_file(pipeline, "output/msd_data.txt",
        format = "txt/attr",
        columns = ["Timestep", "MSD"],
        multiple_frames = True)