Internal registry that owns backend states and tracks qubit membership and location. More...

#include <q2ns-qstate-registry.h>

Collaboration diagram for q2ns::QStateRegistry:

Public Types
using	StreamAssigner = std::function< void(QState &)>
	Callback type used to assign RNG streams to newly registered states.

Public Member Functions
void	SetStreamAssigner (StreamAssigner fn)
	Set the callback used to assign streams to newly created states.

void	SetDefaultBackend (QStateBackend b)
	Set the default backend used for newly created states.

QStateBackend	GetDefaultBackend () const
	Get the default backend used for newly created states.

CreateStateResult	CreateState (unsigned int n)
	Create a new state with n qubits initialized in the \|0...0> state.

CreateStateResult	CreateStateFromExisting (const std::shared_ptr< QState > &state)
	Register an already-constructed backend state object.

std::shared_ptr< QState >	MergeStates (const std::vector< std::shared_ptr< Qubit > > &qs)
	Ensure the provided qubits belong to a single backend state.

void	RemoveState (StateId id)
	Remove a backend state and its membership tracking.

std::shared_ptr< QState >	GetState (StateId stateId) const
	Get a backend state by state id.

std::shared_ptr< QState >	GetState (const std::shared_ptr< Qubit > &q) const
	Get the backend state associated with a qubit handle.

void	Register (const std::shared_ptr< Qubit > &q)
	Register a qubit handle as a member of its current state.

void	Unregister (const std::shared_ptr< Qubit > &q)
	Unregister a qubit handle from its current state membership list.

void	UnregisterEverywhere (const std::shared_ptr< Qubit > &q)
	Remove a qubit handle from membership lists across all states.

void	SetLocation (const std::shared_ptr< Qubit > &q, Location loc)
	Set the tracked location for a qubit handle.

void	SetLocation (QubitId id, Location loc)
	Set the tracked location for a qubit id.

Location	GetLocation (const std::shared_ptr< Qubit > &q) const
	Get the tracked location for a qubit handle.

Location	GetLocation (QubitId id) const
	Get the tracked location for a qubit id.

std::vector< QubitId >	GetQubitsAtNode (uint32_t nodeId) const
	Return qubit ids currently located at a given node.

std::shared_ptr< Qubit >	GetQubitHandle (QubitId id) const
	Return a tracked qubit handle by qubit id.

std::vector< std::shared_ptr< Qubit > >	GetLocalQubits (uint32_t nodeId) const
	Return qubit handles currently located at a given node.

std::vector< std::shared_ptr< Qubit > >	QubitsOf (StateId stateId) const
	Return qubit handles that currently belong to a given state.

std::vector< std::shared_ptr< QState > >	GetStatesSortedById () const
	Return all registered states sorted by state id.

Private Attributes
StreamAssigner	streamAssigner_ {}
	Callback used when a new state is registered.

QStateBackend	defaultBackend_ = QStateBackend::Ket
	Default backend for CreateState().

StateId	nextStateId_ = 1
	Next state id to assign.

QubitId	nextQubitId_ = 1
	Next qubit id to assign.

std::unordered_map< StateId, std::shared_ptr< QState > >	states_
	State id to backend state.

std::unordered_map< StateId, std::vector< std::shared_ptr< Qubit > > >	members_
	State id to shared member qubit handles.

std::unordered_map< QubitId, Location >	location_
	Qubit id to current location.

std::unordered_map< uint32_t, std::unordered_set< QubitId > >	qubitsAtNode_
	Node id to currently local qubit ids.

std::unordered_map< QubitId, std::shared_ptr< Qubit > >	qubitById_
	Qubit id to shared handle.

Detailed Description

Internal registry that owns backend states and tracks qubit membership and location.

QStateRegistry is not intended to be a primary user-facing API. It acts as the central source of truth for:

backend state ownership
qubit membership within each state
current qubit location
qubit-id to handle resolution

QNode, QProcessor, QNetworker, and NetController rely on this registry to coordinate state evolution, movement, and lookup.

See also: QNode; QProcessor; QNetworker; NetController

Definition at line 63 of file q2ns-qstate-registry.h.

Member Typedef Documentation

◆ StreamAssigner

using q2ns::QStateRegistry::StreamAssigner = std::function<void(QState&)>

Callback type used to assign RNG streams to newly registered states.

Definition at line 68 of file q2ns-qstate-registry.h.

Member Function Documentation

◆ CreateState()

CreateStateResult q2ns::QStateRegistry::CreateState ( unsigned int n )

Create a new state with n qubits initialized in the |0...0> state.

Parameters

n	Number of qubits in the new state.

Returns: Result containing the assigned state id and initial qubit indices.

See also: CreateStateFromExisting

Definition at line 51 of file q2ns-qstate-registry.cc.

References defaultBackend_, q2ns::DM, q2ns::Ket, members_, nextStateId_, sid, q2ns::Stab, states_, and streamAssigner_.

Referenced by q2ns::QProcessor::CreateBellPair(), and q2ns::QProcessor::CreateQubit().

Here is the caller graph for this function:

◆ CreateStateFromExisting()

CreateStateResult q2ns::QStateRegistry::CreateStateFromExisting ( const std::shared_ptr< QState > & state )

Register an already-constructed backend state object.

The caller is responsible for binding qubits to the returned state id and indices and then calling Register() for each qubit handle.

Parameters

state Backend state to register.

Returns: Result containing the assigned state id and initial qubit indices.

See also: CreateState; Register

Definition at line 88 of file q2ns-qstate-registry.cc.

References members_, nextStateId_, states_, and streamAssigner_.

Referenced by q2ns::QProcessor::CreateQubit(), and q2ns::QProcessor::Measure().

Here is the caller graph for this function:

◆ GetDefaultBackend()

QStateBackend q2ns::QStateRegistry::GetDefaultBackend ( ) const

Get the default backend used for newly created states.

Returns: Current backend enum value.

See also: SetDefaultBackend

Definition at line 47 of file q2ns-qstate-registry.cc.

References defaultBackend_.

Referenced by q2ns::NetController::GetQStateBackend().

Here is the caller graph for this function:

◆ GetLocalQubits()

std::vector< std::shared_ptr< Qubit > > q2ns::QStateRegistry::GetLocalQubits ( uint32_t nodeId ) const

Return qubit handles currently located at a given node.

The returned vector is a snapshot taken at call time. Element order is not guaranteed.

Parameters

nodeId Node identifier.

Returns: Snapshot of qubit handles currently local to that node.

See also: GetQubitsAtNode

Definition at line 386 of file q2ns-qstate-registry.cc.

Referenced by q2ns::QProcessor::GetLocalQubits(), and q2ns::QProcessor::GetQubit().

Here is the caller graph for this function:

◆ GetLocation() [1/2]

Location q2ns::QStateRegistry::GetLocation ( const std::shared_ptr< Qubit > & q ) const

Get the tracked location for a qubit handle.

Parameters

q	Qubit handle.

Returns: Current location if tracked, otherwise an Unset location.

See also: GetLocation(QubitId)

Definition at line 338 of file q2ns-qstate-registry.cc.

References q2ns::MakeUnsetLocation().

Referenced by q2ns::QProcessor::Apply(), q2ns::Qubit::GetLocation(), q2ns::QProcessor::GetQubit(), q2ns::QProcessor::Measure(), q2ns::QProcessor::MeasureBell(), q2ns::Qubit::SetLocationChannel(), and q2ns::Qubit::SetLocationNode().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetLocation() [2/2]

Location q2ns::QStateRegistry::GetLocation ( QubitId id ) const

Get the tracked location for a qubit id.

Parameters

id Qubit id.

Returns: Current location if tracked, otherwise an Unset location.

See also: GetLocation(const std::shared_ptr<Qubit>&)

Definition at line 352 of file q2ns-qstate-registry.cc.

References q2ns::MakeUnsetLocation().

Here is the call graph for this function:

◆ GetQubitHandle()

std::shared_ptr< Qubit > q2ns::QStateRegistry::GetQubitHandle ( QubitId id ) const

Return a tracked qubit handle by qubit id.

Parameters

id	Qubit identifier.

Returns: Shared pointer to the qubit handle, or nullptr if unknown.

See also: GetQubitsAtNode; GetLocalQubits

Definition at line 377 of file q2ns-qstate-registry.cc.

Referenced by q2ns::QProcessor::GetQubit().

Here is the caller graph for this function:

◆ GetQubitsAtNode()

std::vector< QubitId > q2ns::QStateRegistry::GetQubitsAtNode ( uint32_t nodeId ) const

Return qubit ids currently located at a given node.

Only qubits whose tracked location is LocationType::Node with matching ownerId are returned.

Parameters

nodeId Node identifier.

Returns: Snapshot of qubit ids currently local to that node.

See also: GetLocalQubits

Definition at line 361 of file q2ns-qstate-registry.cc.

◆ GetState() [1/2]

std::shared_ptr< QState > q2ns::QStateRegistry::GetState ( const std::shared_ptr< Qubit > & q ) const

Get the backend state associated with a qubit handle.

Parameters

q	Qubit handle.

Returns: Shared pointer to the state, or nullptr if the qubit is null or unknown.

See also: GetState(StateId)

Definition at line 422 of file q2ns-qstate-registry.cc.

◆ GetState() [2/2]

std::shared_ptr< QState > q2ns::QStateRegistry::GetState ( StateId stateId ) const

Get a backend state by state id.

Parameters

stateId State identifier.

Returns: Shared pointer to the state, or nullptr if unknown.

See also: GetState(const std::shared_ptr<Qubit>&)

Definition at line 430 of file q2ns-qstate-registry.cc.

Referenced by q2ns::NetController::GetState(), q2ns::QProcessor::GetState(), q2ns::QProcessor::Measure(), and MergeStates().

Here is the caller graph for this function:

◆ GetStatesSortedById()

std::vector< std::shared_ptr< QState > > q2ns::QStateRegistry::GetStatesSortedById ( ) const

Return all registered states sorted by state id.

This provides deterministic iteration order for operations such as delayed RNG stream assignment.

Returns: Vector of states sorted by state id.

See also: SetStreamAssigner

Definition at line 220 of file q2ns-qstate-registry.cc.

Referenced by q2ns::NetController::AssignStreams().

Here is the caller graph for this function:

◆ MergeStates()

std::shared_ptr< QState > q2ns::QStateRegistry::MergeStates ( const std::vector< std::shared_ptr< Qubit > > & qs )

Ensure the provided qubits belong to a single backend state.

If all qubits already belong to one state, that state is returned unchanged. Otherwise, the involved states are merged, qubits are rebound to the merged state with compacted indices, and empty predecessor states are removed.

Parameters

qs	Qubits that must share one backend state.

Returns: Shared pointer to the resulting backend state, or nullptr if the merge is rejected.

See also: GetState; RemoveState

Definition at line 112 of file q2ns-qstate-registry.cc.

References GetState(), QubitsOf(), and sid.

Referenced by q2ns::QProcessor::Apply().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ QubitsOf()

std::vector< std::shared_ptr< Qubit > > q2ns::QStateRegistry::QubitsOf ( StateId stateId ) const

Return qubit handles that currently belong to a given state.

Parameters

stateId State identifier.

Returns: Snapshot of qubit handles in that state.

See also: GetState

Definition at line 404 of file q2ns-qstate-registry.cc.

Referenced by q2ns::QProcessor::Measure(), and MergeStates().

Here is the caller graph for this function:

◆ Register()

void q2ns::QStateRegistry::Register ( const std::shared_ptr< Qubit > & q )

Register a qubit handle as a member of its current state.

If the qubit does not yet have a stable qubit id, one is assigned here. If the qubit does not yet have a tracked location, it is marked Unset.

Parameters

q	Qubit handle.

See also: Unregister; SetLocation

Definition at line 240 of file q2ns-qstate-registry.cc.

References q2ns::MakeUnsetLocation(), and sid.

Referenced by q2ns::QProcessor::CreateBellPair(), q2ns::QProcessor::CreateQubit(), q2ns::QProcessor::CreateQubit(), and q2ns::QProcessor::Measure().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RemoveState()

void q2ns::QStateRegistry::RemoveState ( StateId id )

Remove a backend state and its membership tracking.

Parameters

id	State id to remove.

See also: MergeStates

Definition at line 215 of file q2ns-qstate-registry.cc.

Referenced by q2ns::QProcessor::Measure().

Here is the caller graph for this function:

◆ SetDefaultBackend()

void q2ns::QStateRegistry::SetDefaultBackend ( QStateBackend b )

Set the default backend used for newly created states.

Parameters

b	Backend enum value.

See also: GetDefaultBackend; BackendFromString

Definition at line 43 of file q2ns-qstate-registry.cc.

References defaultBackend_.

Referenced by q2ns::NetController::SetQStateBackend(), and q2ns::NetController::SetQStateBackend().

Here is the caller graph for this function:

◆ SetLocation() [1/2]

void q2ns::QStateRegistry::SetLocation	(	const std::shared_ptr< Qubit > &	q,
		Location	loc
	)

Set the tracked location for a qubit handle.

This also ensures the global qubit-id directory can resolve the qubit id back to the handle.

Parameters

q	Qubit handle.
loc	Location descriptor.

See also: GetLocation

Definition at line 306 of file q2ns-qstate-registry.cc.

Referenced by q2ns::QProcessor::Measure(), q2ns::Qubit::SetLocationChannel(), q2ns::Qubit::SetLocationLost(), and q2ns::Qubit::SetLocationNode().

Here is the caller graph for this function:

◆ SetLocation() [2/2]

void q2ns::QStateRegistry::SetLocation	(	QubitId	id,
		Location	loc
	)

Set the tracked location for a qubit id.

Parameters

id	Qubit id.
loc	Location descriptor.

See also: GetLocation

Definition at line 316 of file q2ns-qstate-registry.cc.

References q2ns::Location::ownerId, and q2ns::Location::type.

◆ SetStreamAssigner()

void q2ns::QStateRegistry::SetStreamAssigner ( StreamAssigner fn )

inline

Set the callback used to assign streams to newly created states.

This is typically installed by NetController so states created after stream assignment receive deterministic streams automatically.

Parameters

fn	Stream-assignment callback.

See also: GetStatesSortedById

Definition at line 80 of file q2ns-qstate-registry.h.

References streamAssigner_.

Referenced by q2ns::NetController::NetController().

Here is the caller graph for this function:

◆ Unregister()

void q2ns::QStateRegistry::Unregister ( const std::shared_ptr< Qubit > & q )

Unregister a qubit handle from its current state membership list.

Parameters

q	Qubit handle.

See also: Register; UnregisterEverywhere

Definition at line 268 of file q2ns-qstate-registry.cc.

References sid.

◆ UnregisterEverywhere()

void q2ns::QStateRegistry::UnregisterEverywhere ( const std::shared_ptr< Qubit > & q )

Remove a qubit handle from membership lists across all states.

Parameters

q	Qubit handle.

See also: Unregister

Definition at line 289 of file q2ns-qstate-registry.cc.

References sid.

Referenced by q2ns::QProcessor::Measure().

Here is the caller graph for this function:

Member Data Documentation

◆ defaultBackend_

QStateBackend q2ns::QStateRegistry::defaultBackend_ = QStateBackend::Ket

private

Default backend for CreateState().

Definition at line 296 of file q2ns-qstate-registry.h.

Referenced by CreateState(), GetDefaultBackend(), and SetDefaultBackend().

◆ location_

std::unordered_map<QubitId, Location> q2ns::QStateRegistry::location_

private

Qubit id to current location.

Definition at line 304 of file q2ns-qstate-registry.h.

◆ members_

std::unordered_map<StateId, std::vector<std::shared_ptr<Qubit> > > q2ns::QStateRegistry::members_

private

State id to shared member qubit handles.

Definition at line 303 of file q2ns-qstate-registry.h.

Referenced by CreateState(), and CreateStateFromExisting().

◆ nextQubitId_

QubitId q2ns::QStateRegistry::nextQubitId_ = 1

private

Next qubit id to assign.

Definition at line 299 of file q2ns-qstate-registry.h.

◆ nextStateId_

StateId q2ns::QStateRegistry::nextStateId_ = 1

private

Next state id to assign.

Definition at line 298 of file q2ns-qstate-registry.h.

Referenced by CreateState(), and CreateStateFromExisting().

◆ qubitById_

std::unordered_map<QubitId, std::shared_ptr<Qubit> > q2ns::QStateRegistry::qubitById_

private

Qubit id to shared handle.

Definition at line 307 of file q2ns-qstate-registry.h.

◆ qubitsAtNode_

std::unordered_map<uint32_t, std::unordered_set<QubitId> > q2ns::QStateRegistry::qubitsAtNode_

private

Node id to currently local qubit ids.

Definition at line 306 of file q2ns-qstate-registry.h.

◆ states_

std::unordered_map<StateId, std::shared_ptr<QState> > q2ns::QStateRegistry::states_

private

State id to backend state.

Definition at line 301 of file q2ns-qstate-registry.h.

Referenced by CreateState(), and CreateStateFromExisting().

◆ streamAssigner_

StreamAssigner q2ns::QStateRegistry::streamAssigner_ {}

private

Callback used when a new state is registered.

Definition at line 294 of file q2ns-qstate-registry.h.

Referenced by CreateState(), CreateStateFromExisting(), and SetStreamAssigner().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ StreamAssigner

Member Function Documentation

◆ CreateState()

◆ CreateStateFromExisting()

◆ GetDefaultBackend()

◆ GetLocalQubits()

◆ GetLocation() [1/2]

◆ GetLocation() [2/2]

◆ GetQubitHandle()

◆ GetQubitsAtNode()

◆ GetState() [1/2]

◆ GetState() [2/2]

◆ GetStatesSortedById()

◆ MergeStates()

◆ QubitsOf()

◆ Register()

◆ RemoveState()

◆ SetDefaultBackend()

◆ SetLocation() [1/2]

◆ SetLocation() [2/2]

◆ SetStreamAssigner()

◆ Unregister()

◆ UnregisterEverywhere()

Member Data Documentation

◆ defaultBackend_

◆ location_

◆ members_

◆ nextQubitId_

◆ nextStateId_

◆ qubitById_

◆ qubitsAtNode_

◆ states_

◆ streamAssigner_