Advanced Topics

This guide covers advanced quantum concepts and techniques for the Unity package. If you're new to Quantum Forge, start with the Getting Started guide.

Design Principles

Keep the Quantum Small

Quantum systems grow exponentially. Keep basis dimensions and property counts as small as possible.

Example: In chess, there are 12 piece types plus empty (13 states). Rather than creating a 13-element Basis, use a 2-element Basis (empty / not empty) and store the piece type classically.

The hard limit on interacting quantum properties is currently 20. Design around this constraint — measure and release properties when no longer needed.

Give Players Control

Give players ways to manipulate the quantum state. During the development of Quantum Chess, players discovered emergent interference effects that the designers didn't anticipate. This is the power of real quantum mechanics — surprising behaviors emerge naturally.

Entanglement

Entanglement is when the state of a quantum system cannot be described by its individual components. In Quantum Forge, you create entanglement through:

Controlled Operations (Predicates)

Any quantum action can be made conditional using predicates. This is the primary mechanism for creating entanglement:

// Apply Hadamard to target ONLY when control is in state "on"
var predicate = new QuantumProperty.Predicate {
    property = controlProperty,
    value = controlProperty.basis.values[0], // "on"
    is_equal = true
};

targetProperty.Hadamard(predicate);
// target and control are now entangled

NCycle

The NCycle action directly entangles two quantum properties:

// Entangle two properties
QuantumProperty.NCycle(prop1, prop2);
// Measuring one now affects the other

iSwap

The iSwap gate creates entanglement with a phase factor:

// Half iSwap — maximal entanglement
QuantumProperty.ISwap(prop1, prop2, 0.5f);

Measurement Correlation

When you measure one entangled property, the other's probabilities update instantly:

int[] result = QuantumProperty.Measure(entangledProp1);
// entangledProp2's state has changed — check its probabilities
var probs = QuantumProperty.Probabilities(entangledProp2);

Phase and Interference

Phase is invisible to direct measurement but critical for interference effects.

PhaseRotate

Apply a specific phase angle to states matching predicates:

var pred = prop.is_value(0);
QuantumProperty.PhaseRotate(Mathf.PI, pred); // π phase on |0⟩

Clock Gate

Apply phase proportional to basis value index:

prop.Clock(0.5f); // fractional clock rotation

Phase + Hadamard = Interference

Phase differences become probability differences after a Hadamard:

prop.Hadamard();                    // create superposition
prop.Clock(0.5f);                   // add phase
prop.Hadamard();                    // convert phase to probability bias
// Probabilities are now unequal — interference!

Trackers

Trackers are MonoBehaviours that continuously monitor quantum state. Add them to GameObjects to inspect quantum behavior in the editor.

ProbabilityTracker

Shows the probability of each basis state. Auto-updates every frame when continuous is enabled.

var tracker = GetComponent<ProbabilityTracker>();
var probs = tracker.Probabilities;
// probs[i].Probability, probs[i].BasisValues

EntanglementTracker

Quantifies entanglement via quantum mutual information (Von Neumann entropy). Requires two or more properties.

var tracker = GetComponent<EntanglementTracker>();
float[] mi = tracker.UpdateMutualInformation();
// Higher values = more entanglement

CorrelationTracker

Computes Pearson's correlation coefficient between property measurement outcomes. Useful for understanding what happens when you measure.

var tracker = GetComponent<CorrelationTracker>();
float[,] matrix = tracker.UpdateCorrelationMatrix();

PhaseTracker

Visualizes relative phases between basis states. Can display in radians or degrees.

var tracker = GetComponent<PhaseTracker>();
float[,] phases = tracker.UpdatePhaseMatrix();

ReducedDensityMatrixTracker

Provides the full mathematical representation of the quantum state. Useful for debugging.

var tracker = GetComponent<ReducedDensityMatrixTracker>();
Complex[,] rdm = tracker.GetReducedDensityMatrix();

Performance

Set trackers to update on demand (disable continuous) and call their update methods manually when needed. Continuous tracking on every frame can be expensive with many properties.

Custom Quantum Actions

Create custom quantum actions by implementing IQuantumAction:

using QRG.QuantumForge.Runtime;

public class MyQuantumAction : MonoBehaviour, IQuantumAction
{
    [SerializeField] private QuantumProperty[] targetProperties;
    [SerializeField] private QuantumProperty.Predicate[] predicates;

    public QuantumProperty.Predicate[] Predicates
    {
        get => predicates;
        set => predicates = value;
    }

    public QuantumProperty[] TargetProperties
    {
        get => targetProperties;
        set => targetProperties = value;
    }

    public void apply()
    {
        foreach (var prop in targetProperties)
        {
            // Your quantum logic here
            prop.Hadamard(predicates);
            prop.Clock(0.25f, predicates);
        }
    }
}

Debugging Tips

• Combine trackers for a complete picture: ProbabilityTracker (what), PhaseTracker (why), EntanglementTracker (how connected)
• Use the Inspector to watch probability distributions change in real time
• Minimize active properties — fewer quantum properties = easier to debug
• Separate independent subsystems — properties that never entangle can live in separate groups

Performance

• The simulation cost grows exponentially with the number of entangled properties
• 20 properties max for interacting systems
• Set trackers to update on demand rather than continuously
• Use controlled operations efficiently — each predicate adds overhead
• Consider measuring and releasing properties when no longer needed

Glossary

Term	Definition
Superposition	A linear combination of basis states — the property is "in multiple states at once"
Basis	The set of possible states (e.g., rock/paper/scissors)
Amplitude	A complex number describing each state's contribution
Phase	The angle of a complex amplitude — critical for interference
Entanglement	When the state of the system can't be described by its parts
Measurement	Collapses superposition to a definite value
Interference	When amplitudes reinforce or cancel each other