Backend-agnostic interface for a quantum state object. More...

#include <q2ns-qstate.h>

Inheritance diagram for q2ns::QState:

Collaboration diagram for q2ns::QState:

Classes
struct	MeasureResult
	Result of measuring one qubit and splitting the state. More...

Public Member Functions
virtual	~QState ()
	Virtual destructor.

virtual int64_t	AssignStreams (int64_t stream)
	Assign RNG streams for deterministic randomness.

StateId	GetStateId () const
	Get the registry-assigned state id.

void	SetStateId (StateId id)
	Set the registry-assigned state id.

virtual void	Print (std::ostream &os) const =0
	Print a human-readable representation of the state.

virtual std::size_t	NumQubits () const =0
	Return the number of logical qubits in the state.

virtual void	Apply (const QGate &g, const std::vector< Index > &targets)=0
	Apply a gate to the given target indices.

virtual std::shared_ptr< QState >	MergeDisjoint (const QState &other) const =0
	Return a new state that is the disjoint merge of this state and another.

virtual MeasureResult	Measure (q2ns::Index target, q2ns::Basis basis=q2ns::Basis::Z)=0
	Measure one qubit and split the result into new states.

Protected Member Functions
void	PrintHeader (std::ostream &os, const char *backendName) const
	Print a standard backend header.

Static Protected Member Functions
static uint64_t	SplitMix64 (uint64_t x)
	Mix a 64-bit value deterministically.

static uint64_t	DeriveSeed64 (uint32_t seed, uint32_t run, int64_t stream, uint64_t salt)
	Derive a deterministic 64-bit seed from ns-3 seed/run and a stream.

static std::seed_seq	MakeSeedSeq (uint64_t s64)
	Build a std::seed_seq from a 64-bit seed.

static void	CheckSeedRunNonZero (uint32_t seed, uint32_t run)
	Abort if ns-3 seed or run is zero.

template<uint64_t SALT>
static bool	ShouldReseed (uint32_t seed, uint32_t run, int64_t stream)
	Return whether a backend-global RNG should be reseeded.

template<uint64_t SALT, typename ReseedFn >
static int64_t	AssignStreamsGlobal (int64_t stream, ReseedFn reseed_fn)
	Helper for backends that reseed a global RNG source.

Private Attributes
StateId	stateId_ {0}
	Registry-assigned state id.

Detailed Description

Backend-agnostic interface for a quantum state object.

QState defines the minimal common interface implemented by concrete backend state classes such as ket, density-matrix, and stabilizer backends.

Design goals:

Keep high-level code backend-agnostic.
Define deterministic index-order semantics for merge and measurement.
Centralize backend stream-assignment helpers shared across implementations.

Concrete implementations may expose backend-specific views on their own concrete classes, but QState provides the common operational interface used by QProcessor and QStateRegistry.

See also: QProcessor; QStateRegistry

Definition at line 51 of file q2ns-qstate.h.

Constructor & Destructor Documentation

◆ ~QState()

q2ns::QState::~QState ( )

virtualdefault

Virtual destructor.

Member Function Documentation

◆ Apply()

virtual void q2ns::QState::Apply	(	const QGate &	g,
		const std::vector< Index > &	targets
	)

pure virtual

Apply a gate to the given target indices.

Concrete backends may support different gate subsets. For example, matrix-based backends may accept arbitrary custom unitaries while other backends may reject non-native operations.

Parameters

g	Gate descriptor.
targets	Target qubit indices.

Implemented in q2ns::QStateStab.

◆ AssignStreams()

virtual int64_t q2ns::QState::AssignStreams ( int64_t stream )

inlinevirtual

Assign RNG streams for deterministic randomness.

Backends that use random sampling should deterministically seed or bind their random sources here using the provided stream index together with the current ns-3 seed and run values.

Backends that consume no random streams may keep the default behavior.

Parameters

stream Starting stream index.

Returns: Number of streams consumed.

Reimplemented in q2ns::QStateDM, q2ns::QStateKet, and q2ns::QStateStab.

Definition at line 70 of file q2ns-qstate.h.

References AssignStreamsGlobal().

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ AssignStreamsGlobal()

template<uint64_t SALT, typename ReseedFn >

static int64_t q2ns::QState::AssignStreamsGlobal	(	int64_t	stream,
		ReseedFn	reseed_fn
	)

inlinestaticprotected

Helper for backends that reseed a global RNG source.

This helper reads ns-3 seed and run values, checks they are valid, skips redundant reseeding when the configuration is unchanged, derives a 64-bit seed, and invokes the provided reseed callback.

Template Parameters

SALT	Backend-specific salt.
ReseedFn	Callback type used to perform backend reseeding.

Parameters

stream	Stream index.
reseed_fn	Callback that accepts the derived 64-bit seed.

Returns: Number of streams conceptually consumed.

Definition at line 255 of file q2ns-qstate.h.

References AssignStreamsGlobal(), CheckSeedRunNonZero(), and DeriveSeed64().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CheckSeedRunNonZero()

static void q2ns::QState::CheckSeedRunNonZero	(	uint32_t	seed,
		uint32_t	run
	)

inlinestaticprotected

Abort if ns-3 seed or run is zero.

Parameters

seed	ns-3 global seed.
run	ns-3 global run.

Definition at line 205 of file q2ns-qstate.h.

References AssignStreamsGlobal().

Referenced by AssignStreamsGlobal().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DeriveSeed64()

static uint64_t q2ns::QState::DeriveSeed64	(	uint32_t	seed,
		uint32_t	run,
		int64_t	stream,
		uint64_t	salt
	)

inlinestaticprotected

Derive a deterministic 64-bit seed from ns-3 seed/run and a stream.

Parameters

seed	ns-3 global seed.
run	ns-3 global run.
stream	Stream index.
salt	Backend-specific salt.

Returns: Derived 64-bit seed.

Definition at line 184 of file q2ns-qstate.h.

References AssignStreamsGlobal(), and SplitMix64().

Referenced by AssignStreamsGlobal().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetStateId()

StateId q2ns::QState::GetStateId ( ) const

inline

Get the registry-assigned state id.

Returns: Current state id.

Definition at line 79 of file q2ns-qstate.h.

References stateId_.

Referenced by PrintHeader().

Here is the caller graph for this function:

◆ MakeSeedSeq()

static std::seed_seq q2ns::QState::MakeSeedSeq ( uint64_t s64 )

inlinestaticprotected

Build a std::seed_seq from a 64-bit seed.

Parameters

s64	Derived 64-bit seed.

Returns: Seed sequence suitable for standard engines.

Definition at line 194 of file q2ns-qstate.h.

References AssignStreamsGlobal().

Referenced by q2ns::QStateDM::AssignStreams(), and q2ns::QStateKet::AssignStreams().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Measure()

virtual MeasureResult q2ns::QState::Measure	(	q2ns::Index	target,
		q2ns::Basis	basis = `q2ns::Basis::Z`
	)

pure virtual

Measure one qubit and split the result into new states.

Survivors preserve their original relative order. Any original indices greater than the measured target shift down by one in the survivors state.

Parameters

target	Index of the qubit to measure.
basis	Measurement basis. Defaults to Z.

Returns: Measurement result containing outcome, measured state, and survivor state.

Implemented in q2ns::QStateStab, q2ns::QStateDM, and q2ns::QStateKet.

◆ MergeDisjoint()

virtual std::shared_ptr< QState > q2ns::QState::MergeDisjoint ( const QState & other ) const

pure virtual

Return a new state that is the disjoint merge of this state and another.

Index-order invariant:

The result first contains this state's qubits in their current index order.
It then contains the other state's qubits in their current index order.

Parameters

other Other state to merge with.

Returns: Newly allocated merged state object.

Implemented in q2ns::QStateDM, q2ns::QStateKet, and q2ns::QStateStab.

◆ NumQubits()

virtual std::size_t q2ns::QState::NumQubits ( ) const

pure virtual

Return the number of logical qubits in the state.

Returns: Number of logical qubits.

Implemented in q2ns::QStateDM, q2ns::QStateKet, and q2ns::QStateStab.

Referenced by q2ns::analysis::Fidelity(), PrintHeader(), q2ns::analysis::Purity(), q2ns::analysis::TraceDistance(), and q2ns::analysis::VonNeumannEntropy().

Here is the caller graph for this function:

◆ Print()

virtual void q2ns::QState::Print ( std::ostream & os ) const

pure virtual

Print a human-readable representation of the state.

Parameters

os	Output stream.

Implemented in q2ns::QStateDM, q2ns::QStateKet, and q2ns::QStateStab.

Referenced by q2ns::operator<<().

Here is the caller graph for this function:

◆ PrintHeader()

void q2ns::QState::PrintHeader	(	std::ostream &	os,
		const char *	backendName
	)		const

inlineprotected

Print a standard backend header.

Parameters

os	Output stream.
backendName	Human-readable backend name.

Definition at line 159 of file q2ns-qstate.h.

References AssignStreamsGlobal(), GetStateId(), and NumQubits().

Referenced by q2ns::QStateDM::Print(), q2ns::QStateKet::Print(), and q2ns::QStateStab::Print().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetStateId()

void q2ns::QState::SetStateId ( StateId id )

inline

Set the registry-assigned state id.

Parameters

id	New state id.

Definition at line 87 of file q2ns-qstate.h.

References stateId_.

◆ ShouldReseed()

template<uint64_t SALT>

static bool q2ns::QState::ShouldReseed	(	uint32_t	seed,
		uint32_t	run,
		int64_t	stream
	)

inlinestaticprotected

Return whether a backend-global RNG should be reseeded.

This caches the most recent seed, run, and stream tuple for a given SALT.

Template Parameters

SALT	Backend-specific salt.

Parameters

seed	ns-3 global seed.
run	ns-3 global run.
stream	Stream index.

Returns: True if reseeding should occur.

Definition at line 221 of file q2ns-qstate.h.

References AssignStreamsGlobal().

Here is the call graph for this function:

◆ SplitMix64()

static uint64_t q2ns::QState::SplitMix64 ( uint64_t x )

inlinestaticprotected

Mix a 64-bit value deterministically.

Parameters

x	Input value.

Returns: Mixed value.

Definition at line 169 of file q2ns-qstate.h.

References AssignStreamsGlobal().

Referenced by DeriveSeed64().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ stateId_

StateId q2ns::QState::stateId_ {0}

private

Registry-assigned state id.

Definition at line 270 of file q2ns-qstate.h.

Referenced by GetStateId(), and SetStateId().

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

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~QState()

Member Function Documentation

◆ Apply()

◆ AssignStreams()

◆ AssignStreamsGlobal()

◆ CheckSeedRunNonZero()

◆ DeriveSeed64()

◆ GetStateId()

◆ MakeSeedSeq()

◆ Measure()

◆ MergeDisjoint()

◆ NumQubits()

◆ Print()

◆ PrintHeader()

◆ SetStateId()

◆ ShouldReseed()

◆ SplitMix64()

Member Data Documentation

◆ stateId_