A-Machine

A-Machine is a library for constructing epsilon-machines¹ 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 for more details.

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

Installation

# CPU only
pip install a-machine

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

# With transformers + torch (CPU), along with aim and datasets
pip install "a-machine[transformers]" --extra-index-url https://download.pytorch.org/whl/cpu

# With transformers + torch (CUDA 13.2) along with aim and datasets
pip install "a-machine[transformers]" --extra-index-url https://download.pytorch.org/whl/cu132

# With all
pip install "a-machine[all]" \
  --extra-index-url https://pypi.nvidia.com \
  --extra-index-url https://download.pytorch.org/whl/cu132

Quick Start

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

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