# 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.
