Installation#
This section guides you through installing, configuring, and verifying QML-HCS — the Quantum Machine Learning Hypercausal System.
It covers installation from source and via PyPI (package mode), environment setup, and first-run validation for both users and contributors.
—
Overview#
QML-HCS provides a research-grade environment for building quantum-inspired causal architectures and exploring hypercausal inference, quantum learning, and non-stationary systems.
You can install QML-HCS in two ways:
As a local editable project (recommended for development and experiments)
As a standard installed package (for users or deployment environments)
The project follows a modern Python packaging layout (PEP 621 + src/ structure) and includes optional extras for development, documentation, and testing.
—
Requirements#
Python 3.9+ (tested on 3.9–3.12)
pip >= 23.0
Git for cloning the repository
Optional: virtual environment manager (venv, Poetry, or Conda)
It is highly recommended to use a virtual environment to isolate dependencies and avoid system-wide conflicts.
—
Installation (Editable Source Mode)#
Clone the repository
git clone https://github.com/Neureonmindflux-Research-Lab/qml-hcs.git cd qml-hcs
Create and activate a virtual environment
python3 -m venv .venv source .venv/bin/activate
(Windows PowerShell)
python -m venv .venv .\.venv\Scripts\Activate.ps1
Upgrade pip and install the package in editable mode
pip install -U pip pip install -e .
This editable mode links your local src/qmlhc folder directly into the environment, so code changes are immediately reflected without reinstalling.
—
Installation (Package Mode)#
The package can be installed directly from PyPI using the standard Python installation command:
pip install qml-hcs
or specify a particular version:
pip install qml-hcs==0.2.0
You can verify installation by running:
python -c "import qmlhcs; print(qmlhcs.__version__)"
This method is ideal for end-users or production deployments where the source code is not being modified, but the full library functionality and API features remain available for direct use.
—
Optional Installation Profiles#
QML-HCS supports modular extras to tailor the installation to your workflow or research needs.
Development tools (linting, typing, packaging):
pip install -e .[dev]
Documentation stack (Sphinx + themes + MyST + rendering tools):
pip install -e .[docs]
Testing suite (pytest + coverage):
pip install -e .[test]
Visualization utilities (matplotlib):
pip install -e .[viz]
All-in-one environment (everything):
pip install -e .[all]
> Each of these groups is defined under [project.optional-dependencies] > in pyproject.toml, allowing you to install only what you need.
—
Verifying Installation#
To confirm that QML-HCS is correctly recognized by Python, run:
python -c "import qmlhc, sys; print('QML-HCS imported successfully on Python', sys.version)"
You should see an output similar to:
QML-HCS imported successfully on Python 3.11.8
If you see ModuleNotFoundError: No module named 'qmlhc',
double-check that your virtual environment is active and the installation succeeded.
—
Running the Minimal Demo#
Once installed, try the minimal example to confirm correct functionality:
qmlhc-demo
or run it directly as a Python module:
python -m qmlhc.examples.ex_minimal_core_demo
This script demonstrates the basic architecture and telemetry output for the quantum hypercausal backend.
Example output
=== Minimal Core Demo ===
output_dim (D): 3
branches (K): 3
x_t: [ 0.2 -0.1 0.4]
S_{t-1} (s_tm1): [ 0.15 -0.05 0.35]
S_t (from run): [ 0.23549575 -0.04496965 0.40532131]
Ŝ_{t+1} (selected): [ 0.22245591 -0.04314564 0.3712728 ]
Node information (summary):
policy: MeanPolicy
branches shape: (3, 3)
branches[0]: [-0.01450323 -0.28670244 0.15408422]
ConsistencyLoss:
α = 1.0, β = 1.0
loss = 0.003909313321780935
HCModel.forward() matches single-node result ✔
Consistency loss definition
Explanation
This minimal example demonstrates the core execution of the Quantum Machine Learning Hypercausal Core (QMLHC). It shows how the system evolves between two consecutive states, evaluates internal consistency, and confirms that the forward operation matches the theoretical expectation.
You can continue exploring this and other runnable examples in the Examples section for more advanced demonstrations of QMLHC models and configurations.
—
Creating Your Own Pipelines#
This section explains how to start building your own code using QMLHC’s core modules.
It follows the same structure as the official examples under src/qmlhc/examples/.
Quick steps
Define a backend: subclass
QuantumBackendand implement the logic ofrunandproject_future.Wrap the backend in an
HCNodeand attach a policy such asMeanPolicy.Combine nodes into an
HCModelorHCGraphdepending on the desired topology.Add a loss such as
ConsistencyLossorTriadicLoss.Optionally train using a lightweight optimizer and callbacks (see training examples).
Minimal skeleton
from qmlhc.core import BackendConfig, QuantumBackend
from qmlhc.hc import HCNode, MeanPolicy
from qmlhc.loss import ConsistencyLoss
import numpy as np
class MyBackend(QuantumBackend):
def run(self, params=None):
x = self._require_input().astype(float)
s = np.tanh(0.9 * x + 0.1)
return self._validate_state(s)
def project_future(self, s_t, branches=3):
s = self._validate_state(s_t)
deltas = np.linspace(-0.25, 0.25, branches)
fut = np.stack([np.tanh(s + d) for d in deltas], axis=0)
return self._validate_branches(fut)
cfg = BackendConfig(output_dim=3)
node = HCNode(backend=MyBackend(cfg), policy=MeanPolicy())
model = HCModel([node])
x_t, s_tm1 = np.array([0.2, -0.1, 0.4]), np.array([0.15, -0.05, 0.35])
s_t, s_hat, info = node.forward(x_t, s_tm1=s_tm1, branches=3)
loss_fn = ConsistencyLoss(alpha=1.0, beta=1.0)
loss = loss_fn(s_tm1, s_t, s_hat)
You can explore more runnable implementations in the Examples section, which includes advanced training, multi-node graphs, and benchmarking demos.
Building the Documentation#
If you installed the docs extras, you can generate the local HTML documentation:
sphinx-build -E -a -b html docs/ docs/_build/html
Then open:
docs/_build/html/index.html
to view the generated site in your browser.
—
Repository Structure#
The QML-HCS repository follows a clean modular layout:
qml-hcs/
├── src/
│ └── qmlhc/ # Core Python package
│ ├── __init__.py
│ ├── core/ # Quantum hypercausal core modules
│ ├── hc/ # Hypercausal policies and dynamics
│ ├── predictors/ # Predictors, operators, and projection layers
│ ├── loss/ # Loss and metric definitions
│ ├── metrics/ # Evaluation metrics and consistency checks
│ ├── optim/ # Optimizers and training utilities
│ ├── callbacks/ # Telemetry and training callbacks
│ ├── backends/ # Interfaces to quantum / hybrid backends
│ └── examples/ # Runnable minimal and advanced examples
│
├── tests/ # Unit and integration tests
│ ├── test_core.py
│ ├── test_loss.py
│ └── ...
│
├── docs/ # Sphinx documentation
│ ├── conf.py
│ ├── index.rst
│ ├── getting_started.rst
│ └── examples.rst
│
├── pyproject.toml # Build metadata (PEP 621)
├── Makefile # Build, test, and docs automation
└── README.md # Project overview and installation guide
This layout ensures a clear separation between the library code (src/qmlhc), tests, documentation, and build configuration.
—
Troubleshooting#
“ModuleNotFoundError: No module named ‘qmlhcs’” This error may occur if the installation did not complete successfully or if the virtual environment is not active. Activate the environment and reinstall using:
pip install qml-hcs
“Command ‘qmlhc-demo’ not found” This issue typically occurs when the package’s console scripts are not available in the system path. Reinstall the package or ensure that the Python environment’s
bin/directory is included in thePATHvariable.“ImportError: cannot import name …” This problem may arise when using an outdated version of the library. Upgrade to the latest release with:
pip install -U qml-hcs
“Documentation build fails” If Sphinx fails to build the documentation due to missing extensions or duplicated
.. toctree::directives, verify that all dependencies are installed and that only one:caption:directive appears per section.“Version mismatch or API not found” Cached or partially installed versions can cause inconsistencies. Clear the environment and reinstall cleanly using:
pip uninstall qml-hcs -y && pip install qml-hcs
Note
If problems persist, report installation or runtime issues through the official issue tracker: GitHub Issues – QML-HCS
—
Next Steps#
Once QML-HCS is installed and verified, explore:
The Examples section for runnable demos
The Core API Reference for detailed class and function documentation
The Benchmark Studies for experimental comparisons
These resources will help you understand how QML-HCS integrates quantum-inspired logic into adaptive, hypercausal neural architectures.
—
By following this setup guide, your environment will be ready for quantum-hypercausal research and development using QML-HCS.
Collaborating and Contributing#
If you’d like to contribute new features, documentation, or examples to QMLHC, please review the Contributing section for basic guidelines on branching, style, and pull-request workflow.
Once your environment is ready, you can verify everything with the test suite below.
Running the Test Suite#
To verify that everything is working correctly, you can run the full test suite or a single test file.
Run all tests
pytest -q --cov=qmlhc --cov-report=term-missing
Run tests with detailed HTML coverage (optional)
To view a detailed coverage report directly in your browser, run:
pytest -q --cov=src/qmlhc --cov-branch --cov-report=html
python -m webbrowser htmlcov/index.html
Run a single test file
pytest tests/test_core.py
Example output
..................................................... [100%]
===================================================================== tests coverage =====================================================================
_____________________________________________ coverage: platform linux, python 3.13.5-final-0 _______________________________________________
Name Stmts Miss Branch BrPart Cover Missing
----------------------------------------------------------------------------------------
src/qmlhc/backends/cpp_backend.py 37 2 8 0 96% 158-159
src/qmlhc/callbacks/base.py 28 1 10 0 97% 118
src/qmlhc/callbacks/depth_control.py 30 6 4 0 82% 93-96, 101, 105, 109, 113
src/qmlhc/callbacks/telemetry.py 52 1 6 2 95% 70->exit, 82
src/qmlhc/core/backend.py 42 3 10 1 92% 120, 142, 234
src/qmlhc/examples/ex_minimal_core_demo.py 56 56 4 0 0% 17-174
src/qmlhc/hc/graph.py 69 0 26 1 99% 221->219
src/qmlhc/metrics/control.py 26 1 6 1 94% 82
----------------------------------------------------------------------------------------
TOTAL 847 70 144 5 92%
25 files skipped due to complete coverage.
Required test coverage of 75.0% reached. Total coverage: 92.03%
53 passed in 0.32s
(.venv) (base) mozoh@pop-os:~/Desktop/P1/qml-hcs$
A 100% test success and a coverage above 90% confirm that the QMLHC package is correctly installed and all major modules are functioning as expected.
Acknowledgments#
We appreciate your interest in QML-HCS and the time taken to review and explore the library. Your feedback and contributions are essential to help us continue refining and expanding the Quantum Machine Learning Hypercausal System as a reliable and innovative research framework.
For suggestions, feature requests, or academic collaborations, please open a discussion or report an issue on our official repository:
Thank you for supporting open research and advancing the development of quantum-inspired machine learning.
—