Q-Matrix

Quantum Fuzzy Sets and the Q-Matrix Framework

A Python reference implementation accompanying the paper:

M. A. Mannucci, Quantum Fuzzy Sets Revisited: Density Matrices, Decoherence, and the Q-Matrix Framework (2026)

Overview

This package implements density-matrix-valued fuzzy sets and the Q-Matrix framework—a generalization of classical fuzzy sets where membership values are density matrices rather than numbers in [0,1]. The density matrix extension naturally represents coherence, decoherence, and entanglement effects absent from ordinary scalar-valued fuzzy sets.

The Q-Matrix is implemented here as one global realization model for generating local density-matrix-valued sections.

qmatrix is the Python package implementing the QFS / Q-Matrix framework.

Status: alpha / reference implementation. This repository accompanies a conceptual/foundational paper. It is intended for illustration and experimentation rather than as a production scientific computing library.

Modules

Module	Contents
qmatrix.core	DensityMatrix, QuantumFuzzySet, QMatrix
qmatrix.categorical	QuantumChannel, QFSMorphism, classicality tests
qmatrix.information	Fidelity, Holevo information, coherence measures
qmatrix.circuits	Qiskit circuit construction (optional)

Installation

pip install -e .             # Core (numpy + scipy)
pip install -e ".[circuits]" # With Qiskit
pip install -e ".[dev]"      # With pytest

Quick start

from qmatrix import DensityMatrix, QuantumFuzzySet, fidelity, is_classical

# Define a quantum fuzzy set
qfs = QuantumFuzzySet({
    "cat": DensityMatrix([[0.7, 0.3], [0.3, 0.3]]),
    "dog": DensityMatrix([[0.4, 0.2], [0.2, 0.6]]),
    "pet": DensityMatrix([[0.5, 0.1], [0.1, 0.5]]),
})

# Semantic similarity via Uhlmann fidelity
print(fidelity(qfs["cat"], qfs["dog"]))   # ≈ 0.890
print(fidelity(qfs["cat"], qfs["pet"]))   # ≈ 0.899
print(fidelity(qfs["dog"], qfs["pet"]))   # ≈ 0.978

# Classicality test: pairwise commutativity
admits, basis = is_classical(qfs)
print(admits)  # False — sections don't commute

# Classical reduction via decoherence
classical = qfs.decohere()
print(classical.membership_values())  # {'cat': 0.3, 'dog': 0.6, 'pet': 0.5}

Q-Matrix: global entangled state

import numpy as np
from qmatrix import QMatrix

# Bell state Q-Matrix
psi = np.array([1, 0, 0, 1], dtype=float) / np.sqrt(2)
qm = QMatrix.from_pure_state(psi, [2, 2], ["A", "B"])

# Local sections via partial trace
rho_A = qm.section("A")
print(rho_A.purity)  # 0.5 — maximally mixed

# Quantum mutual information: 2 bits (maximal)
print(qm.mutual_information("A", "B"))  # 2.0

Categorical structure

from qmatrix import QuantumChannel, QFSMorphism, identity_morphism

# A unitary morphism (Pauli-X bit flip)
X = np.array([[0, 1], [1, 0]])  # Pauli-X
channel = QuantumChannel.unitary(X)

source = QuantumFuzzySet({
    "off": DensityMatrix([[1, 0], [0, 0]]),
    "on":  DensityMatrix([[0, 0], [0, 1]]),
})
target = QuantumFuzzySet({
    "on":  DensityMatrix([[1, 0], [0, 0]]),
    "off": DensityMatrix([[0, 0], [0, 1]]),
})

m = QFSMorphism(source, target, {"off": "off", "on": "on"}, channel)
print(m.is_isomorphism())  # True
m_dag = m.dagger()         # (f⁻¹, Φ⁻¹) — defined for isomorphisms only

Examples

python examples/cat_dog_pet.py           # Running example: QFS basics
python examples/semantic_entanglement.py  # Bell state Q-Matrix
python examples/categorical_structure.py  # Morphisms, dagger, tensor product

Tests

pytest tests/ -v  # 40 tests

Citation

@article{mannucci2025qmatrix,
  title={Quantum Fuzzy Sets Revisited: Density Matrices, Decoherence, and the Q-Matrix Framework},
  author={Mannucci, M. A.},
  year={2026}
}

License

MIT