Metadata-Version: 2.4
Name: a-machine
Version: 0.2.0
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://tneuroth.gitlab.io/a-machine/amachine.html
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: 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
Requires-Dist: ipython>=9.13.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.

See the [documentation](https://tneuroth.gitlab.io/a-machine/amachine.html#what-is-a-machine) for more details.

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
import amachine as am

# Seeds random and np.random globally (alternatively pass a random seed directly to random_machine)
am.srand_global( 42 )

# May have multiple recurrent subgraphs, terminal states, or tranistory states
m = am.random_machine( 
	n_states=23, 
	symbols=[ '0', '1' ],
	connectedness=0.35,
	randomness=0.25 )

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

# Minimize the machine in case it's not minimal -> epsilon-machine.
m.minimize( retain_names=True )

# Single symbol entropy, entropy rate, Statistical complexity
print( f"H(1) : {m.H_1():.3f}" )
print( f"h_mu : {m.h_mu():.3f}" )
print( f"C_mu : {m.C_mu():.3f}" )

# Excess entropy, transient information, synchronization information 
print( f"E : {m.E():.3f}" )
print( f"T : {m.T_inf():.3f}" )
print( f"S : {m.S():.3f}" )

# Crypticity
print( f"chi : {m.chi():.3f}" )

# Display the epislon machine
m.draw_graph(output_dir=".")
```

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