Metadata-Version: 2.5
Name: fatqat
Version: 0.1.0a1
Summary: A quantum computing toolkit for building, compiling, and executing quantum programs.
Project-URL: Homepage, https://github.com/spaceqat/fatqat
Project-URL: Documentation, https://fatqat.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/spaceqat/fatqat
Project-URL: Issues, https://github.com/spaceqat/fatqat/issues
Author: FatQat contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: quantum circuits,quantum computing,quantum noise,quantum simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: loky>=3.0.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: numba>=0.59
Requires-Dist: numpy>=1.26
Requires-Dist: qutip-qip<0.5,>=0.4
Requires-Dist: qutip<6,>=5.1
Requires-Dist: scipy<2,>=1.12
Description-Content-Type: text/markdown

# FatQat

FatQat is a quantum-computing toolkit built around one authoring interface:
`Program`. Write the computation once, then choose how closely to model the
machine beneath it.

> **Development status:** FatQat is under active development, and its interfaces
> may change between releases. Pin an exact version when reproducibility matters.

| Execution level | Start here when you want to… |
| --- | --- |
| General simulation | study logical states, samples, observables, noise, or parameter sweeps |
| Hardware-profile simulation | check native operations, placement, connectivity, capacity, or atom occupancy |
| Hamiltonian emulation | follow pulses, coupling, leakage, timing, and continuous-time noise |

The execution targets accept the same `Program` type and return results through
the same `Job`/`Result` workflow. Each target still validates what it can
physically or mathematically realize.

## Installation

FatQat requires Python 3.12 or newer. Install FatQat:

```sh
python -m pip install fatqat
```

To work on the development version, install from a source checkout:

```sh
git clone https://github.com/spaceqat/fatqat.git
cd fatqat
python -m pip install .
```

## Run a first Program

This Bell-state example contains the complete circuit-level workflow:

```python
import fatqat as fq
import fatqat.operations as ops

program = fq.Program(2, 2)
program.add(ops.H, 0)
program.add(ops.CX, (0, 1))
program.measure_all()

result = fq.simulator.Simulator().run(
    program,
    shots=1000,
    simulation_config={"seed": 7},
).result()

print(result.get_counts())
```

Only `00` and `11` appear: the measured bits agree because the two qubits are
entangled. The
[quickstart](https://fatqat.readthedocs.io/en/latest/guide/quickstart/)
draws this Program, runs it, and turns the counts into a plot.

## Grow the same authoring model

`Program` records registers and ordered instructions. It supports gates,
measurement, reset, classical conditions, reusable parameters, logical qudits,
mixed local dimensions, circuit drawing, and direct physical controls. These
features stay together instead of splitting into separate circuit and pulse
languages.

The
[Program guide](https://fatqat.readthedocs.io/en/latest/guide/program/)
builds those ideas step by step.
[Choose how much physics to model](https://fatqat.readthedocs.io/en/latest/guide/execution-models/)
then runs one unchanged rotation through all three execution levels.

From there:

- [Simulate a quantum program](https://fatqat.readthedocs.io/en/latest/guide/simulation/) for states,
  sampling, and parameter sweeps.
- [Ask questions of a run](https://fatqat.readthedocs.io/en/latest/guide/interpret-results/) for counts,
  states, maps, and observables.
- [Compare ideal and noisy execution](https://fatqat.readthedocs.io/en/latest/guide/ideal-and-noisy/).
- [Measure performance and scaling](https://fatqat.readthedocs.io/en/latest/guide/performance/).
- [Test a hardware profile](https://fatqat.readthedocs.io/en/latest/guide/hardware-profile-simulation/).
- [Follow a Program into physical dynamics](https://fatqat.readthedocs.io/en/latest/guide/hamiltonian-emulation/),
  then continue with the transmon or neutral-atom workflow.
- [Connect OpenQASM and Qiskit](https://fatqat.readthedocs.io/en/latest/guide/interoperability/).

The [tutorial gallery](https://fatqat.readthedocs.io/en/latest/tutorials/)
contains longer algorithm and physics case studies. The
[API reference](https://fatqat.readthedocs.io/en/latest/api/)
contains the exact signatures, supported operations, shapes, units, and
validation contracts.

Release notes are in the
[changelog](https://github.com/spaceqat/fatqat/blob/main/CHANGELOG.md).

## Development

For basic local development, install the source tree with the core test
dependencies:

```sh
python -m pip install --upgrade pip
python -m pip install --editable . --group dev
python -m pytest
```

Before preparing a contribution, install the full test and lint environment:

```sh
python -m pip install --editable . --group test-full --group lint
```

`test-full` includes the `dev` dependencies and the optional Qiskit integration
dependencies. `lint` adds Black and Pylint.

Before submitting a change, read
[Contributing to FatQat](https://github.com/spaceqat/fatqat/blob/main/CONTRIBUTING.md),
including the policy for AI-assisted work. AI tools are permitted, but every
contributor must understand, own, and lead the work they submit and the project
conversations around it.

For documentation changes, follow the
[pinned setup and build workflow](https://github.com/spaceqat/fatqat/blob/main/docs/mkdocs/README.md).

The main repository directories are:

- `src/fatqat/` — package source.
- `tests/` — behavior-focused test suite.
- `docs/mkdocs/` — Material user guide, executable tutorials, and API reference.
