Fock state classes

FockState

class exqalibur.FockState

A FockState is an immutable container representing the positions of n indistinguishable photons in m modes.

>>> from exqalibur import FockState
>>> state = FockState([1, 2, 3])  # 1 photon in the first mode, 2 in the second mode, and 3 in the last mode
>>> print(f"{state} containing {state.n} photons)
|1,2,3> containing 6 photons

inject_annotation(*args, **kwargs)

Overloaded function.

1. inject_annotation(self: exqalibur.FockState, tag: typing.SupportsInt) -> NoisyFockState

Parameters:

tag – The noise tag to inject in this state

Returns:

A NoisyFockState where photons are at the same position than in self, all with the specified noise tag.

2. inject_annotation(self: exqalibur.FockState, annot: exqalibur.Annotation) -> exqalibur.AnnotatedFockState

Parameters:

annot – The annotation to inject

Returns:

A new state where photons are at the same position and are all annotated with annot

property m

Returns:

The number of modes

merge(*args, **kwargs)

Overloaded function.

1. merge(self: exqalibur.FockState, arg0: exqalibur.FockState) -> exqalibur.FockState

Parameters:

other – a Fock state object of any type with the same number of modes than self.

Returns:

A new state for which the photons the addition of the photons in self and in other. the type of the state is automatically inferred from self and other so that it can contain all the information. Rules:

• A FockState photons are converted to {0} to give a NoisyFockState.

• A NoisyFockState photons are converted to {_:noise_tag} for an AnnotatedFockState.

2. merge(self: exqalibur.FockState, arg0: NoisyFockState) -> NoisyFockState

3. merge(self: exqalibur.FockState, arg0: exqalibur.AnnotatedFockState) -> exqalibur.AnnotatedFockState

mode2photon(self: exqalibur.FockState, mode: SupportsInt) → int

Parameters:

mode – The mode of the photon.

Returns:

The index of the first photon in the given mode (when photons are ordered mode by mode), or -1 if the mode is empty.

property n

Returns:

The number of photons

partition(self: exqalibur.FockState, vector: collections.abc.Sequence[SupportsInt]) → list[std::vector<FockState, std::allocator<FockState> >]

photon2mode(self: exqalibur.FockState, n: SupportsInt) → int

Parameters:

n – The photon index.

Returns:

The mode of the nth photon, where photons are sorted by ascending mode number.

prodnfact(self: exqalibur.FockState) → float

Returns:

The product of factorials of the photon count in each mode (self[0]! * self[1]! * ... * self[m-1]!)

remove_modes(self: exqalibur.FockState, modes: collections.abc.Sequence[SupportsInt]) → exqalibur.FockState

Parameters:

modes – The list of modes to remove.

Returns:

A new state with only the modes that are not in modes

set_slice(*args, **kwargs)

Overloaded function.

1. set_slice(self: exqalibur.FockState, arg0: slice, arg1: NoisyFockState) -> NoisyFockState

2. set_slice(self: exqalibur.FockState, arg0: slice, arg1: exqalibur.AnnotatedFockState) -> exqalibur.AnnotatedFockState

3. set_slice(self: exqalibur.FockState, arg0: slice, arg1: exqalibur.FockState) -> exqalibur.FockState

4. set_slice(self: exqalibur.FockState, arg0: exqalibur.FockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.FockState

Creates a new state from self with a section replaced by an other state.

Parameters:

• other – The state to replace part of self with. Must have \(end - start\) modes

• start – The first mode to replace.

• end – The last mode to replace (excluded).

Returns:

A new state, promoted to the smallest possible type given self and other, where the section between start and end is other, and the remaining comes from self.

5. set_slice(self: exqalibur.FockState, arg0: NoisyFockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> NoisyFockState

6. set_slice(self: exqalibur.FockState, arg0: exqalibur.AnnotatedFockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.AnnotatedFockState

slice(self: exqalibur.FockState, arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsInt) → exqalibur.FockState

threshold_detection(*args, **kwargs)

Overloaded function.

1. threshold_detection(self: exqalibur.FockState) -> exqalibur.FockState

2. threshold_detection(self: exqalibur.FockState, threshold: typing.SupportsInt) -> exqalibur.FockState

Parameters:

threshold – Maximum number of photons per mode.

Returns:

a new FockState where the photon count of mode m is min(threshold, self[m])

NoisyFockState

class exqalibur.NoisyFockState

A NoisyFockState is a collection of one or several batches of indistinguishable photons where the photons from different batches are distinguishable. We represent the batches using an integer tag (between 0 and 255). Like for AnnotatedFockState, we represent the photons using braces, but we only put the noise tag inside the bracket.

NoisyFockState are constructed with a FockState and a list of noise tags of size n where each tag corresponds to the tag of one photon, starting from mode 0.

>>> from exqalibur import FockState, NoisyFockState
>>> fs = FockState([1, 0, 2])
>>> nfs = NoisyFockState(fs, [0, 0, 1])
>>> print(nfs)
|{0},0,{0}{1}>

clear_annotations(self: exqalibur.NoisyFockState) → exqalibur.FockState

Returns:

The underlying FockState containing only the photon positions

get_mode_annotations(self: exqalibur.NoisyFockState, m: SupportsInt) → list[int]

Parameters:

m – The mode to get the annotations from.

Returns:

A list of all noise tags on this mode, with repetition if more than 1 photon share the same tag.

get_photon_annotation(self: exqalibur.NoisyFockState, n: SupportsInt) → int

Parameters:

n – The photon to take the noise from, where photons are sorted mode by mode.

Returns:

The noise tag of the given photon.

property has_annotations

Returns:

True if the state has any photon with annotation, False otherwise.

inject_annotation(self: exqalibur.NoisyFockState, *args, **kwargs) → None

property m

Returns:

The number of modes

merge(*args, **kwargs)

Overloaded function.

1. merge(self: exqalibur.NoisyFockState, arg0: exqalibur.NoisyFockState) -> exqalibur.NoisyFockState

Parameters:

other – a Fock state object of any type with the same number of modes than self.

Returns:

A new state for which the photons the addition of the photons in self and in other. the type of the state is automatically inferred from self and other so that it can contain all the information. Rules:

• A FockState photons are converted to {0} to give a NoisyFockState.

• A NoisyFockState photons are converted to {_:noise_tag} for an AnnotatedFockState.

2. merge(self: exqalibur.NoisyFockState, arg0: exqalibur.FockState) -> exqalibur.NoisyFockState

3. merge(self: exqalibur.NoisyFockState, arg0: exqalibur.AnnotatedFockState) -> exqalibur.AnnotatedFockState

mode2photon(self: exqalibur.NoisyFockState, mode: SupportsInt) → int

Parameters:

mode – The mode of the photon.

Returns:

The index of the first photon in the given mode (when photons are ordered mode by mode), or -1 if the mode is empty.

property n

Returns:

The number of photons

photon2mode(self: exqalibur.NoisyFockState, n: SupportsInt) → int

Parameters:

n – The photon index.

Returns:

The mode of the nth photon, where photons are sorted by ascending mode number.

prodnfact(self: exqalibur.NoisyFockState) → float

Returns:

The product of factorials of the photon count in each mode (self[0]! * self[1]! * ... * self[m-1]!)

remove_modes(self: exqalibur.NoisyFockState, modes: collections.abc.Sequence[SupportsInt]) → exqalibur.NoisyFockState

Parameters:

modes – The list of modes to remove.

Returns:

A new state with only the modes that are not in modes

separate_state(self: exqalibur.NoisyFockState) → std::vector<FockState, std::allocator<FockState> >

Separate a noisy state into a list of perfect Fock states. All intra-state photons are all indistinguishables, whereas inter-state ones are all distinguishable.

>>> state = NoisyFockState(FockState([1, 2]), [0, 0, 1])
>>> print(state.separate_state())
[ |1, 1>, |0, 1> ]

Returns:

A list of Fock states where each represents a collection of indistinguishable photons from the original state

set_slice(*args, **kwargs)

Overloaded function.

1. set_slice(self: exqalibur.NoisyFockState, arg0: slice, arg1: exqalibur.FockState) -> exqalibur.NoisyFockState

2. set_slice(self: exqalibur.NoisyFockState, arg0: slice, arg1: exqalibur.AnnotatedFockState) -> exqalibur.AnnotatedFockState

3. set_slice(self: exqalibur.NoisyFockState, arg0: slice, arg1: exqalibur.NoisyFockState) -> exqalibur.NoisyFockState

4. set_slice(self: exqalibur.NoisyFockState, arg0: exqalibur.FockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.NoisyFockState

5. set_slice(self: exqalibur.NoisyFockState, arg0: exqalibur.NoisyFockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.NoisyFockState

Creates a new state from self with a section replaced by an other state.

Parameters:

• other – The state to replace part of self with. Must have \(end - start\) modes

• start – The first mode to replace.

• end – The last mode to replace (excluded).

Returns:

A new state, promoted to the smallest possible type given self and other, where the section between start and end is other, and the remaining comes from self.

6. set_slice(self: exqalibur.NoisyFockState, arg0: exqalibur.AnnotatedFockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.AnnotatedFockState

slice(self: exqalibur.NoisyFockState, arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsInt) → exqalibur.NoisyFockState

split_state(self: exqalibur.NoisyFockState) → dict[int, exqalibur.FockState]

>>> state = NoisyFockState(FockState([1, 2]), [0, 0, 1])
>>> print(state.split_state())
{0: |1, 1>, 1: |0, 1>}

Returns:

A dict of states where each state represents a collection of indistinguishable photons from the original state, associated with the noise tag they were defined with.

threshold_detection(*args, **kwargs)

Overloaded function.

1. threshold_detection(self: exqalibur.NoisyFockState) -> exqalibur.FockState

2. threshold_detection(self: exqalibur.NoisyFockState, threshold: typing.SupportsInt) -> exqalibur.FockState

Parameters:

threshold – Maximum number of photons per mode.

Returns:

a new FockState where the photon count of mode m is min(threshold, self[m])

AnnotatedFockState

class exqalibur.Annotation

An Annotation is a mapping between string keys representing annotation names, and (complex) values that can be any number.

They are primarily used to annotate photons in AnnotatedStates.

Usage example:

>>> import exqalibur as xq
>>> annot = xq.Annotation("a:0,b:1+2j")
>>> state = xq.FockState([1, 1])
>>> print(state.inject_annotation(a))
|{a:0,b:(1,2)},{a:0,b:(1,2)}>

get(self: exqalibur.Annotation, k: str, default: complex) → complex

retrieve an annotation or a default value

str_value(self: exqalibur.Annotation, tag: str) → str

give string representation of the tag value

class exqalibur.AnnotatedFockState

An annotated Fock state aims at being a general descriptor of a state. It maps Annotations to photons in order to perform state arithmetic with any kind of photons you might want (annotated with wavelength, polarization…)

However, since it is generally impossible to infer how annotations should be translated into distinguishability, you will need to write a translator to something that Perceval can handle before using it in a simulation.

>>> from exqalibur import AnnotatedFockState
>>> state = AnnotatedFockState("|0, {lambda:625.2}, {lambda:625.3}>")

clear_annotations(self: exqalibur.AnnotatedFockState) → FockState

Returns:

The underlying FockState containing only the photon positions

get_mode_annotations(self: exqalibur.AnnotatedFockState, m: SupportsInt) → list[exqalibur.Annotation]

Parameters:

m – The mode to get the annotations from.

Returns:

A list of all annotations on this mode, with repetition if more than one photon share the same annotation.

get_photon_annotation(self: exqalibur.AnnotatedFockState, n: SupportsInt) → exqalibur.Annotation

Parameters:

n – The photon to take the annotation from, where photons are sorted mode by mode.

Returns:

The Annotation of the given photon.

property has_annotations

Returns:

True if the state has any photon with annotation, False otherwise.

property has_polarization

Returns:

True if the state has any photon with polarization annotation (key “P”), False otherwise.

inject_annotation(self: exqalibur.AnnotatedFockState, annot: exqalibur.Annotation) → None

Parameters:

annot – The annotation to inject

Returns:

A new state where photons are at the same position and are all annotated with annot

property m

Returns:

The number of modes

merge(*args, **kwargs)

Overloaded function.

1. merge(self: exqalibur.AnnotatedFockState, arg0: exqalibur.AnnotatedFockState) -> exqalibur.AnnotatedFockState

Parameters:

other – a Fock state object of any type with the same number of modes than self.

Returns:

A new state for which the photons the addition of the photons in self and in other. the type of the state is automatically inferred from self and other so that it can contain all the information. Rules:

• A FockState photons are converted to {0} to give a NoisyFockState.

• A NoisyFockState photons are converted to {_:noise_tag} for an AnnotatedFockState.

2. merge(self: exqalibur.AnnotatedFockState, arg0: FockState) -> exqalibur.AnnotatedFockState

3. merge(self: exqalibur.AnnotatedFockState, arg0: NoisyFockState) -> exqalibur.AnnotatedFockState

mode2photon(self: exqalibur.AnnotatedFockState, mode: SupportsInt) → int

Parameters:

mode – The mode of the photon.

Returns:

The index of the first photon in the given mode (when photons are ordered mode by mode), or -1 if the mode is empty.

property n

Returns:

The number of photons

photon2mode(self: exqalibur.AnnotatedFockState, n: SupportsInt) → int

Parameters:

n – The photon index.

Returns:

The mode of the nth photon, where photons are sorted by ascending mode number.

prodnfact(self: exqalibur.AnnotatedFockState) → float

Returns:

The product of factorials of the photon count in each mode (self[0]! * self[1]! * ... * self[m-1]!)

remove_modes(self: exqalibur.AnnotatedFockState, modes: collections.abc.Sequence[SupportsInt]) → exqalibur.AnnotatedFockState

Parameters:

modes – The list of modes to remove.

Returns:

A new state with only the modes that are not in modes

set_slice(*args, **kwargs)

Overloaded function.

1. set_slice(self: exqalibur.AnnotatedFockState, arg0: slice, arg1: FockState) -> exqalibur.AnnotatedFockState

2. set_slice(self: exqalibur.AnnotatedFockState, arg0: slice, arg1: NoisyFockState) -> exqalibur.AnnotatedFockState

3. set_slice(self: exqalibur.AnnotatedFockState, arg0: slice, arg1: exqalibur.AnnotatedFockState) -> exqalibur.AnnotatedFockState

4. set_slice(self: exqalibur.AnnotatedFockState, arg0: FockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.AnnotatedFockState

5. set_slice(self: exqalibur.AnnotatedFockState, arg0: NoisyFockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.AnnotatedFockState

6. set_slice(self: exqalibur.AnnotatedFockState, arg0: exqalibur.AnnotatedFockState, arg1: typing.SupportsInt, arg2: typing.SupportsInt) -> exqalibur.AnnotatedFockState

Creates a new state from self with a section replaced by an other state.

Parameters:

• other – The state to replace part of self with. Must have \(end - start\) modes

• start – The first mode to replace.

• end – The last mode to replace (excluded).

Returns:

A new state, promoted to the smallest possible type given self and other, where the section between start and end is other, and the remaining comes from self.

slice(self: exqalibur.AnnotatedFockState, arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsInt) → exqalibur.AnnotatedFockState

threshold_detection(*args, **kwargs)

Overloaded function.

1. threshold_detection(self: exqalibur.AnnotatedFockState) -> FockState

2. threshold_detection(self: exqalibur.AnnotatedFockState, threshold: typing.SupportsInt) -> FockState

Parameters:

threshold – Maximum number of photons per mode.

Returns:

a new FockState where the photon count of mode m is min(threshold, self[m])