4.5.5 pde.storage.movie module

Defines a class storing data on the file system as a compressed movie

This package requires the optional ffmpeg-python package to use FFmpeg for reading and writing movies.

class MovieStorage(filename, *, vmin=0, vmax=1, bits_per_channel=8, video_format='auto', bitrate=-1, info=None, write_mode='truncate_once', write_times=False, loglevel='warning')[source]

Bases: StorageBase

store discretized fields in a movie file

This storage only works when the ffmpeg program and ffmpeg is installed. The default codec is FFV1, which supports lossless compression for various configurations. Not all video players support this codec, but VLC usually works quite well.

Note that important metainformation is stored as a comment in the movie, so this data must not be deleted or altered if the video should be read again.

Warning

This storage potentially compresses data and can thus lead to loss of some information. The data quality depends on many parameters, but most important are the bits per channel of the video format and the range that is encoded (determined by vmin and vmax).

Note also that selecting individual time points might be quite slow since the video needs to be read from the beginning each time. Instead, it is much more efficient to process entire videos (by iterating over them or using items()).

Parameters:

  • filename (str) – The path where the movie is stored. The file extension determines the container format of the movie. The standard codec FFV1 plays well with the “.avi”, “.mkv”, and “.mov” container format.

  • vmin (float or array) – Lowest values that are encoded (per field). Smaller values are clipped to this value.

  • vmax (float or array) – Highest values that are encoded (per field). Larger values are clipped to this value.

  • bits_per_channel (int) – The number of bits used per color channel. Typical values are 8 and 16. The relative accuracy of stored values is 0.01 and 0.0001, respectively.

  • video_format (str) – Identifier for a video format from formats, which determines the number of channels, the bit depth of individual colors, and the codec. The special value auto tries to find a suitable format automatically, taking bits_per_channel into account.

  • bitrate (float) – The bitrate of the movie (in kilobits per second). The default value of -1 let’s the encoder choose an appropriate bit rate.

  • info (dict) – Supplies extra information that is stored in the storage alongside additional information necessary to reconstruct fields and grids.

  • write_mode (str) – Determines how new data is added to already existing data. Possible values are: ‘append’ (data is always appended), ‘truncate’ (data is cleared every time this storage is used for writing), or ‘truncate_once’ (data is cleared for the first writing, but appended subsequently). Alternatively, specifying ‘readonly’ will disable writing completely.

  • write_times (bool) – Flag determining whether timestamps are written to a file. If True, a separate file with name filename + ".times" is created where the times are written as plain text. Without these timestamps, the time information might be inaccurate.

  • loglevel (str) – FFmpeg log level determining the amount of data sent to stdout. The default only emits warnings and errors, but setting this to “info” can be useful to get additioanl information about the encoding.

clear()[source]

truncate the storage by removing all stored data.

close()[source]

close the currently opened file

Return type:

None

property data

The actual data for all times

Type:

ndarray

end_writing()[source]

finalize the storage after writing

Return type:

None

items()[source]

iterate over all times and stored fields, returning pairs

Return type:

Iterator[tuple[float, FieldBase]]

start_writing(field, info=None)[source]

initialize the storage for writing data

Parameters:

  • field (FieldBase) – An example of the data that will be written to extract the grid and the data_shape

  • info (dict) – Supplies extra information that is stored in the storage

Return type:

None

times: Sequence[float]

The times at which data is available

Type:

ndarray

tracker(interrupts=1, *, transformation=None)[source]

create object that can be used as a tracker to fill this storage

Parameters:

  • interrupts (InterruptsBase | float | str | Sequence[float] | ndarray) – Determines when the tracker interrupts the simulation. A single numbers determines an interval (measured in the simulation time unit) of regular interruption. A string is interpreted as a duration in real time assuming the format ‘hh:mm:ss’. A list of numbers is taken as explicit simulation time points. More fine- grained contol is possible by passing an instance of classes defined in interrupts.

  • transformation (callable, optional) – A function that transforms the current state into a new field or field collection, which is then stored. This allows to store derived quantities of the field during calculations. The argument needs to be a callable function taking 1 or 2 arguments. The first argument always is the current field, while the optional second argument is the associated time.

Returns:

The tracker that fills the current storage

Return type:

StorageTracker

Example

The transformation argument allows storing additional fields:

def add_to_state(state):
    transformed_field = state.smooth(1)
    return field.append(transformed_field)

storage = pde.MemoryStorage()
tracker = storage.tracker(1, transformation=add_to_state)
eq.solve(..., tracker=tracker)

In this example, storage will contain a trajectory of the fields of the simulation as well as the smoothed fields. Other transformations are possible by defining appropriate add_to_state()