merlin.core.sectored_distribution

SectoredDistribution

class merlin.core.sectored_distribution.SectoredDistribution(sectors)

Bases: object

Probability output spanning multiple photon-number sectors.

sectors: tuple[SectorResult, ...]

get_sector(n_photons)

Return the SectorResult associated with n_photons.

Return type:: SectorResult

total_probability()

Returns the total probability across the sectors.

Return type:: Tensor

to(*args, **kwargs)

Return a new SectoredDistribution with SectorResults moved/cast via torch.Tensor.to.

Parameters:

*args – Positional arguments forwarded to torch.Tensor.to().
**kwargs – Keyword arguments forwarded to torch.Tensor.to().

Returns:

Converted sectored distribution.

Return type:

SectoredDistribution

clone()

Return a cloned SectoredDistribution with metadata and logical performance preserved.

Returns:: Cloned sectored distribution.
Return type:: SectoredDistribution

detach()

Return a detached SectoredDistribution sharing data without gradients.

Returns:: Detached sectored distribution.
Return type:: SectoredDistribution

requires_grad_(requires_grad=True)

Set requires_grad on underlying tensors and return self.

Parameters:: requires_grad (bool) – Whether gradients should be tracked.
Returns:: The updated instance.
Return type:: SectoredDistribution

to_tensor(return_keys=False)

Convert the SectoredDistribution to a single concatenated tensor.

Concatenates probability tensors from all sectors in photon-number order. For batched distributions, maintains all leading batch dimensions and concatenates along the state dimension.

Parameters:

return_keys (bool) – If True, also return the list of keys corresponding to each state in the output tensor. Default is False.

Returns:

torch.Tensor – If return_keys is False: concatenated probability tensor of shape (total_states,) for unbatched or (batch_shape…, total_states) for batched.
tuple[list[tuple[int, …]], torch.Tensor] – If return_keys is True: tuple of (keys, tensor) where keys is a list of tuples representing Fock occupation numbers for each state.

Examples

>>> sector1 = SectorResult(
...     tensor=torch.tensor([0.5, 0.5]),
...     n_modes=2,
...     n_photons=1,
... )
>>> sector2 = SectorResult(
...     tensor=torch.tensor([0.3, 0.3, 0.4]),
...     n_modes=2,
...     n_photons=2,
... )
>>> dist = SectoredDistribution(sectors=(sector1, sector2))
>>> tensor = dist.to_tensor()
>>> tensor.shape
torch.Size([5])
>>> keys, tensor = dist.to_tensor(return_keys=True)
>>> len(keys)
5

SectorResult

class merlin.core.sectored_distribution.SectorResult(tensor, n_modes, n_photons, computation_space=ComputationSpace.FOCK, keys=None)

Bases: object

One photon-number sector of a probability output. If keys are not given, the Combinadics.enumerate_states will be used.

tensor: Tensor

n_modes: int

n_photons: int

computation_space: ComputationSpace = 'fock'

keys: Optional[tuple[tuple[int, ...], ...]] = None

to(*args, **kwargs)

Return a new state vector moved or cast via torch.Tensor.to.

Parameters:

*args – Positional arguments forwarded to torch.Tensor.to().
**kwargs – Keyword arguments forwarded to torch.Tensor.to().

Returns:

Converted sector result.

Return type:

SectorResult

clone()

Return a cloned SectorResult with identical metadata and normalization flag.

Returns:: Cloned sector result.
Return type:: SectorResult

detach()

Return a detached SectorResult sharing data without gradients.

Returns:: Detached sector result.
Return type:: SectorResult

requires_grad_(requires_grad=True)

Set requires_grad on the underlying tensor and return self.

Parameters:: requires_grad (bool) – Whether gradients should be tracked.
Returns:: The updated instance.
Return type:: SectorResult