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.

Two hard limits come from the shipped native plugin, which is compiled with MAX_DIMENSION=3, MAX_NUM_QUDITS=12 and dynamic fallback turned off:

• A Basis can hold at most 3 values. A 4-value Basis is not slow, it fails: QuantumProperty.Awake cannot create the native property and logs a warning, leaving the component inert. There is no fallback path to a larger dimension.
• At most 12 quantum properties can interact. Design around it. Measure and release properties when you no longer need them.

QuantumForge.GetMaxDimension() and QuantumForge.GetMaxQudits() report what the loaded plugin was built with, and QuantumForge.IsValidDimension(d) checks a single dimension.

Give Players Control

Give players ways to manipulate the quantum state. During the development of Quantum Chess, players discovered interference effects that the designers didn't anticipate. Real quantum mechanics does that: the math produces behaviors nobody planned for.

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 Predicate {
    property = controlProperty,
    value = controlProperty.basis.values[0], // "on"
    is_equal = true
};

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

Predicate is a class in QRG.QuantumForge.Runtime, not a nested type on QuantumProperty. Because it is a class and not a struct, an element of a Predicate[] you never assigned is null, and the gate call rejects it with an ArgumentException. The shorter way to build one is controlProperty.is_value("on") or controlProperty.is_not_value(0).

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). Unlike the other trackers it does not fall back to the QuantumProperty on its own GameObject, so you have to assign at least two properties in the Inspector. With fewer than two it logs an error and UpdateMutualInformation() returns null.

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 Predicate[] predicates;

    public 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
• 12 properties max for interacting systems
• Set trackers to update on demand rather than continuously
• Use controlled operations efficiently, since 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