Metadata-Version: 2.4
Name: q-alchemy-visualization
Version: 0.1.0
Summary: Renderer-neutral experiment diagrams and text and Matplotlib renderers for Q-Alchemy
Author: data cybernetics ssc GmbH
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/data-cybernetics/q-alchemy-visualization
Project-URL: Documentation, https://github.com/data-cybernetics/q-alchemy-visualization#readme
Project-URL: Repository, https://github.com/data-cybernetics/q-alchemy-visualization.git
Project-URL: Issues, https://github.com/data-cybernetics/q-alchemy-visualization/issues
Keywords: quantum-computing,visualization,experiment-diagrams,matplotlib,q-alchemy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mpl
Requires-Dist: matplotlib>=3.8; extra == "mpl"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: matplotlib>=3.8; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Q-Alchemy Visualization

`q-alchemy-visualization` provides a small, renderer-neutral model for experiment
flow diagrams, plus text and Matplotlib renderers. It is designed for reports
produced by Q-Alchemy libraries, but the diagram model can be used independently.

The package contains no service client, credentials, feasibility decisions, or
quantum execution logic. Text rendering has no runtime dependencies. Matplotlib
is optional and imported only when graphical output is requested.

> **Project status:** Alpha. The versioned wire format is stable within schema
> version 1, but renderer features may expand in later releases.

## Installation

Install the dependency-free text renderer from PyPI:

```bash
python -m pip install q-alchemy-visualization
```

Install graphical rendering support with:

```bash
python -m pip install "q-alchemy-visualization[mpl]"
```

Python 3.11 and newer are supported.

## Quick start

```python
from q_alchemy.visualization import (
    ExperimentConnection,
    ExperimentDiagram,
    ExperimentStep,
    ExperimentStepStatus,
)

diagram = ExperimentDiagram(
    title="EXPERIMENT EXECUTION",
    steps=(
        ExperimentStep("PREPARE", status=ExperimentStepStatus.RUN, key="prepare"),
        ExperimentStep(
            "CLASSICAL",
            details=("Assessment: feasible",),
            status=ExperimentStepStatus.RUN,
            key="classical",
        ),
        ExperimentStep(
            "QUANTUM",
            details=("Assessment: compared",),
            status=ExperimentStepStatus.RUN,
            key="quantum",
        ),
    ),
    connections=(
        ExperimentConnection("prepare", "classical"),
        ExperimentConnection("classical", "quantum"),
    ),
)

print(diagram.draw(output="text", show_title=True))

# Requires the `mpl` extra. The caller owns the returned Figure.
figure = diagram.draw(output="mpl", show_title=True)
figure.savefig("experiment.png", bbox_inches="tight")
```

## Wire format

Diagrams serialize to a versioned JSON-compatible representation so producers
and renderers do not need to share workflow-specific code:

```python
payload = diagram.to_dict()
restored = ExperimentDiagram.from_dict(payload)

encoded = diagram.to_json(indent=2)
restored_from_json = ExperimentDiagram.from_json(encoded)
```

Schema version 1 uses this structure:

```json
{
  "schema_version": 1,
  "kind": "experiment-diagram",
  "title": "EXPERIMENT EXECUTION",
  "nodes": [
    {
      "id": "classical",
      "title": "CLASSICAL",
      "details": ["Assessment: feasible"],
      "status": "run"
    }
  ],
  "edges": []
}
```

The wire representation contains no renderer coordinates, Matplotlib objects,
ASCII layout, or Q-Alchemy feasibility rules. Explicit connections must form a
directed acyclic graph. The current compact text layout supports at most two
nodes per layer and connections between adjacent layers.

Titles are hidden by default. Pass `show_title=True` to either renderer to show
the diagram title.

## Public API

The top-level package exports:

- `ExperimentDiagram`
- `ExperimentStep`
- `ExperimentStepStatus`
- `ExperimentConnection`
- `TextExperimentDrawer`
- `MatplotlibExperimentDrawer`
- `DIAGRAM_SCHEMA_VERSION`

## Development

Clone the repository, create an environment, and run the tests:

```bash
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest
```

Build and validate the distributions before proposing a release:

```bash
.venv/bin/python -m build
.venv/bin/python -m twine check dist/*
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and release guidance.

## License

Licensed under the [Apache License 2.0](LICENSE).
