Metadata-Version: 2.4
Name: a-machine
Version: 0.1.1
Summary: Construct epsilon-machines to generate symbol sequences with ground truth causal structure and information-theoretic complexity for studying neural network learning dynamics.
Author-Email: "Tyson A. Neuroth" <tyneuroth@gmail.com>
License-Expression: MIT
License-File: LICENCSE
Project-URL: Homepage, https://gitlab.com/tneuroth/a-machine
Project-URL: Repository, https://gitlab.com/tneuroth/a-machine
Project-URL: Issues, https://gitlab.com/tneuroth/a-machine/-/boards
Requires-Python: >=3.12
Requires-Dist: hnswlib
Requires-Dist: matplotlib
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: orjson
Requires-Dist: pyarrow
Requires-Dist: pygraphviz
Requires-Dist: scikit-umfpack
Requires-Dist: scipy
Requires-Dist: graphviz>=0.21
Requires-Dist: automata-lib>=9.2.0
Requires-Dist: sympy>=1.14.0
Requires-Dist: pdoc>=16.0.0
Requires-Dist: nanobind>=2.12.0
Provides-Extra: cuda
Requires-Dist: cupy-cuda13x>=14.0.1; extra == "cuda"
Requires-Dist: cuvs-cu13==26.4.*; extra == "cuda"
Description-Content-Type: text/markdown

# A-Machine

A-Machine is a library for constructing epsilon-machines[^1] and other stochastic models for generating structured symbol sequences. It was created with the goal of generating data with ground truth causal structure and information-theoretic complexity for studying neural network learning dynamics and internal representations.

This is an early work in progress. Much more to come.

## Installation

```bash
# CPU only
pip install a-machine

# With GPU support (requires CUDA 13)
pip install "a-machine[cuda]" --extra-index-url https://pypi.nvidia.com

## Quick Start

```python
from amachine.am_create import random_machine

# May have multiple recurrent subgraphs, terminal states, or tranistory states
m = random_machine( 
	n_states=11, 
	symbols=[ '0', '1', '2' ],
	connectedness=0.75,
	randomness=0.35 )

# Collapse to the largest recurrent subgraph
m.collapse_to_largest_strongly_connected_subgraph()

# Minimize the machine -> epsilon-machine.
m.minimize()

# Entropy rate, statistical complexity, excess entropy, crypticity 
print( f"h_mu : {m.h_mu()}" )
print( f"C_mu : {m.C_mu()}" )
print( f"Chi  : {m.Chi()}" )

# Draw the graph 
m.draw_graph( output_dir=".", show=True )
```

## Author

Tyson A. Neuroth

[tneuroth.gitlab.io](https://tneuroth.gitlab.io)

## Citation

If you use this package in your research, please cite:

```
@software{a-machine,
  author = {Tyson A. Neuroth},
  title  = {A-Machine},
  year   = {2016},
  url    = {https://gitlab.com/tneuroth/a-machine}
}
```

## License

MIT

## References

[^1]: Crutchfield, James P., and Karl Young. "Inferring statistical complexity." Physical review letters 63.2 (1989): 105.
