requsim.events module

Classes:

`Event`(time[, required_objects, priority, ...])	Abstract base class for events.
`GenericEvent`(time, resolve_function, *args)	Event that executes arbitrary function.
`SourceEvent`(time, source, initial_state[, ...])	An Event generating an entangled pair.
`EntanglementSwappingEvent`(time, pairs, station)	An event to perform entanglement swapping.
`DiscardQubitEvent`(time, qubit[, priority, ...])	Event to discard a qubit and associated pair.
`EntanglementPurificationEvent`(time, pairs, ...)	Perform a step of an entanglement purification protocol.
`UnblockEvent`(time, quantum_objects[, ...])	Unblock a set of quantum objects.
`EventQueue`()	Provides methods to queue and resolve Events in order.

class requsim.events.Event(time, required_objects=None, priority=20, ignore_blocked=False, callback_functions=None, *args, **kwargs)

Bases: ABC

Abstract base class for events.

Events are scheduled in an EventQueue and resolved at a specific time. The resolution is performed by calling the Event.resolve method once. Subclasses of Event need to overwrite the Event._main_effect method to perform the desired action the event represents. All references the _main_effect needs should be provided at initialization.

Parameters:

time (scalar) – The time at which the event will be resolved.
required_objects (list of QuantumObjects, or None) – Event will only resolve if all of these still exist at time. Default: None
priority (int (expected 0...39)) – prioritize events that happen at the same time according to this (lower number means being resolved first) Default: 20
ignore_blocked (bool) – Whether the event should act even on blocked objects. Default: False
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None

Variables:

event_queue (EventQueue) – The event is part of this event queue. (None until added to an event queue.)
time
required_objects
priority
ignore_blocked
callback_functions

Attributes:

type

Returns the event type.

Methods:

`req_objects_exist`()	Check if all required objects still exist in the world.
`resolve`()	Resolve the event.
`add_callback`(callback_func)	Add a callback to this event.

property type

Returns the event type.

Returns:: str – The event type.

req_objects_exist()

Check if all required objects still exist in the world.

Useful to check if the event is outdated.

Returns:: bool – True if all required objects still exist, False otherwise.

resolve()

Resolve the event.

Returns:

dict – The return dict dict can be used by a protocol or callbacks. Specific events may provide additional key-value pairs, but will always contain at least:

”event”Event: The event object itself. While all necessary information should be provided with separate keys, this can be used as a fallback.
”event_type”str: The type property of this event.
”resolve_successful”bool: False if something prevented the resolution of the event, e.g. the required quantum objects no longer exist. Note that this indicates only whether the event could be resolved according to the event system rules, and not the success or failure of an event with an inherently probabilistic effect (such as entanglement purification).

add_callback(callback_func)

Add a callback to this event.

Multiple callbacks added this way will resolve in the order they were added.

Parameters:: callback_func (callable) – This function will be called with the _return_dict as an argument after the event is resolved.
Returns:: None

class requsim.events.GenericEvent(time, resolve_function, *args, required_objects=None, priority=20, ignore_blocked=False, callback_functions=None, **kwargs)

Bases: Event

Event that executes arbitrary function.

Additional information in return dict of resolve method: whatever resolve_function returns.

Parameters:

time (scalar) – Time at which the event will be resolved.
resolve_function (callable) – Function that will be called when the resolve method is called.
*args (any) – args for resolve_function.
required_objects (list of QuantumObjects, or None) – Keyword only argument. Default: None
priority (int) – Keyword only argument. Default: 20
ignore_blocked (bool) – Keyword only argument. Default: False
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None
**kwargs (any) – kwargs for resolve_function.

class requsim.events.SourceEvent(time, source, initial_state, callback_functions=None, *args, **kwargs)

Bases: Event

An Event generating an entangled pair.

Additional information in return dict of resolve method:

“source”Source: The source that generated the pair.
“output_pair”Pair: The pair that was generated.

Parameters:

time (scalar) – Time at which the event will be resolved.
source (Source) – The source object generating the entangled pair.
initial_state (np.ndarray) – Density matrix of the two qubit system being generated.
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None
*args – additional optional args and kwargs to pass to the the generate_pair method of source
**kwargs – additional optional args and kwargs to pass to the the generate_pair method of source

Variables:

source
initial_state
generation_args (additional args for the generate_pair method of source)
generation_kwargs (additional kwargs for the generate_pair method of source)

class requsim.events.EntanglementSwappingEvent(time, pairs, station, callback_functions=None)

Bases: Event

An event to perform entanglement swapping.

Additional information in return dict of resolve method:

“output_pair”Pair: The resulting pair after the entanglement swapping operation.
“swapping_station”Station: The station that performed the entanglement swapping.

Parameters:

time (scalar) – Time at which the event will be resolved.
pairs (list of Pairs) – The left pair and the right pair.
station (Station) – The station where the entanglement swapping is performed.
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None

Variables:

pairs
station

class requsim.events.DiscardQubitEvent(time, qubit, priority=39, ignore_blocked=True, callback_functions=None)

Bases: Event

Event to discard a qubit and associated pair.

For example if the qubit sat in memory too long and is discarded.

Additional information in return dict of resolve method: None

Parameters:

time (scalar) – Time at which the event will be resolved.
qubit (Qubit) – The Qubit that will be discarded.
priority (int) – Default: 39 (because discard events should get processed last)
ignore_blocked (bool) – Whether the event should act on blocked quantum objects. Default: True
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None

Variables:

qubit

class requsim.events.EntanglementPurificationEvent(time, pairs, communication_time, protocol='dejmps', callback_functions=None)

Bases: Event

Perform a step of an entanglement purification protocol.

Additional information in return dict of resolve method:

“output_pair”Pair: The output pair of the entanglement purification step.
“is_successful”bool: True if the entanglement purification was successful, false if not.

Parameters:

time (scalar) – Time at which the event will be resolved.
pairs (list of Pairs) – The pairs involved in the entanglement purification protocol. Make sure these are at the correct stations and have the same qubit ordering.
communication_time (scalar) – how long it takes for the result of the protocol to be communcated the remaining pair will be blocked for that amount of time
protocol ({"dejmps"} or callable) – Can be one of the pre-defined or an arbitrary callable that takes a tensor product of pair states as input and returns a tuple of (success probability, state of a single pair) back. So far only supports n->1 protocols.
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None

Variables:

pairs
protocol
communication_time

class requsim.events.UnblockEvent(time, quantum_objects, priority=0, callback_functions=None)

Bases: Event

Unblock a set of quantum objects.

This is useful to mark the time when necessary classical information has arrived and the quantum objects may be used by the protocol again. (e.g. after entanglement purification)

Additional information in return dict of resolve method:

“unblocked_objects”list of WorldObject: All objects that were unblocked by this event.

Parameters:

time (scalar) – Time at which the event will be resolved.
quantum_objects (list of QuantumObjects) – The quantum objects to be unblocked.
priority (int (expected 0...39)) – Default: 0 (because unblocking should happen as soon as possible)
callback_functions (list of callables, or None) – these will be called in order, after the event has been resolved. Callbacks can also be added with the add_callback method. Default: None

Variables:

quantum_objects

class requsim.events.EventQueue

Bases: object

Provides methods to queue and resolve Events in order.

Variables:

queue (list of Events) – An ordered list of future events to resolve.
current_time (scalar) – The current time of the event queue.

Attributes:

next_event

Helper property to access next scheduled event.

Methods:

`add_event`(event)	Add an event to the queue.
`resolve_next_event`()	Remove the next scheduled event from the queue and resolve it.
`resolve_until`(target_time)	Resolve events until target_time is reached.
`advance_time`(time_interval)	Helper method to manually advance time.
`print_stats`()	Print stats about the events scheduled and resolved so far.
`remove_by_condition`(condition)	Remove events from event queue if a condition is met.
`add_recurring_filter`(condition, filter_interval)	Add a condition to remove invalid events in a regular interval.
`add_event_type_callback`(event_class, ...)	Add a callback to all events of a certain type.

property next_event

Helper property to access next scheduled event.

Returns:: Event or None – The next scheduled event. None if the event queue is empty.

add_event(event)

Add an event to the queue.

The queue is sorted again in order to schedule the event at the correct time.

Parameters:: event (Event) – The Event to be added to the queue.
Returns:: None
Raises:: ValueError – If event.time is in the past.

resolve_next_event()

Remove the next scheduled event from the queue and resolve it.

Returns:: dict – A dict with at least keys “event_type” and “resolve_successful”, may have additional keys with additional information that can be passed to the protocol.

resolve_until(target_time)

Resolve events until target_time is reached.

Parameters:: target_time (scalar) – Resolve until current_time is this.
Returns:: None
Raises:: ValueError – If target_time lies in the past.

advance_time(time_interval)

Helper method to manually advance time.

Parameters:: time_interval (int) – The amount of time that passes.
Returns:: None
Raises:: ValueError – If an event is skipped during the time_interval.

print_stats()

Print stats about the events scheduled and resolved so far.

Returns:: None

remove_by_condition(condition)

Remove events from event queue if a condition is met.

Removing means they will not be resolved and very importantly, their callbacks will not be triggered.

Parameters:: condition (callable) – This function will be called with the event as argument for every event in the queue. If it returns something Truthy, the event will be removed.
Returns:: list[Event] – All removed events.

add_recurring_filter(condition, filter_interval)

Add a condition to remove invalid events in a regular interval.

The remove_by_condition method will be called with this condition after filter_interval events have been resolved using the resolve_next_event method.

Parameters:

condition (callable) – This function will be called with an event as argument. Should return True if the event should be removed from the queue.
filter_interval (int) – The condition will be checked after filter_interval events have been resolved.

Returns:

None

add_event_type_callback(event_class, callback_func)

Add a callback to all events of a certain type.

In terms of resolution order, the callback will be added after the callbacks that are already present when it is added the queue. For events that are already in the queue, the callbacks will be added after the ones that are already present when this method is called.

Parameters:

event_class (subclass of Event) – The callback will be added to all events that are instances of this class (or a subclass).
callback_func (callables) – This function will be added to the list of callbacks of the specified events. This means it will be called with the return dictionary of the event’s resolve method.

Returns:

None