Creates a new quantum circuit with specified number of qubits.
Initializes an empty quantum circuit ready for gate operations and measurements. The circuit automatically optimizes memory usage for large qubit systems and provides comprehensive validation for all operations.
Circuit Capabilities:
Number of quantum units in the circuit (must be positive integer)
Optional_optimizeMemory: booleanMemory optimization hint (currently auto-determined, reserved for future use)
Get the number of qubits in the circuit.
Returns the total number of quantum bits (qubits) that this circuit operates on. This value is set during circuit construction and may be automatically expanded when gates are applied to higher-indexed qubits.
The number of qubits in the circuit
Returns a copy of all instructions in this circuit.
Provides access to the complete list of quantum operations (gates and measurements) that have been added to this circuit. The returned array is a shallow copy, so modifications to the array will not affect the circuit, but modifications to individual instruction objects will affect the original circuit.
A copy of the circuit's instruction list
Execute the circuit and return the resulting quantum state.
Run the quantum circuit starting from a given initial state.
This method applies all circuit instructions to the provided initial state and returns the resulting quantum state. It supports both pure quantum evolution and measurement-based computations with full state control.
Key Features:
State Validation:
The initial quantum state to start from
The final quantum state after applying all circuit instructions
Resets the circuit to its initial empty state.
Removes all gates, measurements, and instructions from the circuit while preserving the number of quantum units. This allows reusing the circuit object for different quantum algorithm implementations without creating a new instance.
What gets reset:
What stays unchanged:
This circuit instance for method chaining
Add a gate at a specific column position in the circuit.
Name of the gate
Qubit indices (Q5mIndex or array of Q5mIndex)
Column position to place the gate
Optionaloptions: GateOptionsGate options
This circuit for chaining
Delete a gate at a specific column position for given wire(s).
This method removes a gate at the specified column position on the target wire(s), serving as the counterpart to addGate() for column-based gate manipulation.
Key behaviors:
Multi-qubit gate handling:
Target wire(s) to look for gates on (Q5mIndex or array of Q5mIndex)
Column position to delete gate from (0-based)
This circuit instance for method chaining
ProtectedgetHelper method to count gates in a specific column for given wires. Used for column-based gate positioning logic.
ProtectedfindHelper method to find the instruction index at a specific column for given wires. Returns -1 if no gate exists at that column.
ProtectedgetHelper method to calculate the maximum column position for multi-qubit gates. For multi-qubit gates, aligns to the largest column position among all wires.
ProtectedshiftHelper method to shift gates at and after a specific position backward by one. Used when inserting gates in the middle of the circuit.
Insert a gate at a specific position in the instruction sequence.
This method allows precise placement of gates within the circuit based on instruction index, enabling fine-grained control over gate ordering.
Key behaviors:
Instruction index where to insert the gate (0-based)
Name of the gate to insert
Target qubit(s) for the gate
Optionaloptions: GateOptionsOptional gate parameters and options
This circuit instance for method chaining
Remove a gate at a specific position in the instruction sequence.
This method removes the instruction at the given index position, allowing precise control over circuit modifications.
Key behaviors:
Instruction index to remove (0-based)
This circuit instance for method chaining
Replace a gate at a specific position with a new gate.
This method replaces the instruction at the given index with a new gate, maintaining the same position in the circuit while changing the operation.
Key behaviors:
Instruction index to replace (0-based)
Name of the new gate
Target qubit(s) for the new gate
Optionaloptions: GateOptionsOptional gate parameters and options
This circuit instance for method chaining
Computes the unitary matrix representation of the circuit.
This method calculates the complete unitary transformation matrix that represents the entire circuit's quantum operations. The matrix is built by multiplying all gate matrices in sequence.
Important notes:
Optionaltolerance: numberOptional numerical tolerance for matrix operations (when omitted, uses high precision mode)
The unitary matrix as a 2D array of Complex numbers
Computes the matrix representation of the circuit.
Alias for toUnitary() for convenience. Returns the same unitary transformation matrix representing the circuit.
Optionaltolerance: numberOptional numerical tolerance for matrix operations (when omitted, uses high precision mode)
The circuit's unitary matrix
Returns a human-readable string representation of the circuit.
The string includes the number of quantum units and a detailed list of all instructions with their applied quantum units. This is useful for debugging, logging, and understanding the circuit structure.
Output format:
A string representation of the circuit structure
Serializes the circuit to simple internal format (save/load).
Creates a simple representation using the internal instruction array format for efficient storage and loading. This format is optimized for performance and direct reconstruction of the circuit without conversion overhead.
Simple format features:
Simple circuit data for efficient storage
Loads circuit data from simple internal format.
Reconstructs the circuit from data created by save(). This method overwrites the current circuit content with the loaded data.
Simple circuit data from save()
This circuit instance for method chaining
Serializes the circuit to JSON interchange format.
Creates a comprehensive JSON representation suitable for long-term storage, cross-platform interchange, and future compatibility. This format includes versioning, metadata, and detailed gate parameter preservation.
JSON format features:
Serialization options
JSON-compatible circuit representation
ProtectedextractExtract clean gate name without parameter info. E.g., "RX(0.785)" -> "RX", "CNOT" -> "CNOT"
ProtectedextractExtract parameters from gate name or properties. Handles parametrized gates like RX, RY, RZ, Phase, etc.
ProtectedserializeHelper method to serialize gate parameters. Concrete classes can override this for specialized parameter handling.
ProtectedcreateCreates the initial quantum state for circuit execution.
Creates a copy of this circuit.
Apply Controlled-X (CX) gate (alias for CNOT).
Measure qubit in specified basis. Acts as a unified interface for all measurement operations:
Measure qubit in specified basis. Acts as a unified interface for all measurement operations:
Measure qubit in specified basis. Acts as a unified interface for all measurement operations:
Optionalname: stringMeasure qubit in custom phase basis.
Optionalname: stringProtectedgetOverride base circuit's getGateFactory to provide concrete gate implementations.
Append a gate to the end of the circuit by name.
Optionaloptions: GateOptionsGet the current memory usage of the circuit's quantum state.
StaticfromDeserializes a Circuit from JSON interchange format.
Creates a new Circuit instance from JSON data created by toJSON(). Supports version compatibility and parameter restoration.
Serialized circuit JSON data
Load options
New Circuit instance
Extended Circuit class with comprehensive quantum gate library.