FrameProducer

class narupatools.frame.frame_producer.FrameProducer(produce: narupatools.frame.frame_producer.ProduceFrameCallback, *, fields: Collection[str] = ('particle.positions', 'particle.elements', 'particle.names', 'particle.types', 'particle.residues', 'residue.names', 'residue.chains', 'chain.names', 'particle.count', 'residue.count', 'chain.count', 'bond.count', 'bond.pairs', 'energy.kinetic', 'energy.potential', 'system.box.vectors'), frame_interval: float = 0.03333333333333333)

Runnable loop that polls a frame source and produces frame at a regular interval.

A FrameProducer operates on a background thread, and at specified intervals produces a FrameData and triggers the on_frame_produced event. However, it only does this if the frame has been marked as dirty by using mark_dirty. If mark_dirty is provided a set of fields that have changed, then only these fields will then be added to the produced frame data.

Inheritance

Methods

__init__	Create a new playable.
add_fields	Add one or more fields that should be produced if possible.
check_task	Check if a task has thrown an exception, and reraise it if so.
health_check	Check background tasks to ensure they have not encountered an exception.
mark_dirty	Indicate that the given fields have been modified.
pause	Pause this object if it is running.
play	Play the given object.
remove_fields	Remove one or more fields that should not be produced.
restart	Restart this back to its initial state.
run	Run this object, potentially in a background thread.
start	An alias for run().
step	Step forward by one step, and then pause the simulation.
stop	Stop the object if it is running.

__init__(produce: narupatools.frame.frame_producer.ProduceFrameCallback, *, fields: Collection[str] = ('particle.positions', 'particle.elements', 'particle.names', 'particle.types', 'particle.residues', 'residue.names', 'residue.chains', 'chain.names', 'particle.count', 'residue.count', 'chain.count', 'bond.count', 'bond.pairs', 'energy.kinetic', 'energy.potential', 'system.box.vectors'), frame_interval: float = 0.03333333333333333)

Create a new playable.

Parameters

playback_interval – Target interval to run this playable at.

add_fields(fields: infinite_sets.infinite_sets.InfiniteSet[str], /) → None

Add one or more fields that should be produced if possible.

Parameters

fields – Set of fields that should be produced.

classmethod check_task(task: Optional[concurrent.futures._base.Future]) → None

Check if a task has thrown an exception, and reraise it if so.

Parameters

task – Background task to check for an exception.

health_check() → None

Check background tasks to ensure they have not encountered an exception.

Calling this allows exceptions raised on background threads to be thrown on the main thread. It is a useful tool for checking if an object has crashed silently in the background.

It is recommended to call this periodically from the main thread to ensure an object is healthy. If no exceptions have occurred, this method will do nothing.

mark_dirty(fields: infinite_sets.infinite_sets.InfiniteSet[str] = everything()) → None

Indicate that the given fields have been modified.

Parameters

fields – Set of fields to mark as dirty.

pause(wait: bool = True) → None

Pause this object if it is running.

This will not cancel the current run if present, merely suspend it until a subsequent call to play() is made.

Parameters

wait – Wait until the pause has actually occurred.

play() → None

Play the given object.

If this is not running, run this on a background thread. Else, unpause if this is paused.

remove_fields(fields: infinite_sets.infinite_sets.InfiniteSet[str], /) → None

Remove one or more fields that should not be produced.

Parameters

fields – Set of fields that should no longer be produced.

restart() → None

Restart this back to its initial state.

run(block: bool = True) → Union[bool, concurrent.futures._base.Future[bool]]

Run this object, potentially in a background thread.

If block is True (as is the default), this object will run in the calling thread. If block is False, it will be run in a background thread.

Parameters

block – Should this block?

Raises

PlayableAlreadyRunningError – Playable is running on another thread.

Returns

If run in blocking mode, returns True if the playable completed and False if it was stopped. If run in non-blocking mode, returns a Future with the same result.

start(block: bool = True) → None

An alias for run().

Parameters

block – Should this block?

step() → None

Step forward by one step, and then pause the simulation.

stop(wait: bool = True) → None

Stop the object if it is running.

If this is running, this object will stop executing at the next available point.

Parameters

wait – Should this call wait until this object has stopped running before returning?

Attributes

always_dirty	Should it be assumed that all fields are always dirty?
is_paused	Is this currently running but paused?
is_playing	Is this currently playing and not paused?
is_running	Is this currently running?
on_frame_produced	Event triggered when a new frame is produced.
playback_interval	Time in seconds between individual steps of this playable.
playback_rate	Number of steps this playable goes through in 1 second.

always_dirty

Should it be assumed that all fields are always dirty?

is_paused

Is this currently running but paused?

is_playing

Is this currently playing and not paused?

is_running

Is this currently running?

This is True even if the playback is paused.

on_frame_produced

Event triggered when a new frame is produced.

playback_interval

Time in seconds between individual steps of this playable.

playback_rate

Number of steps this playable goes through in 1 second.