# TriuneCadence

TriuneCadence is a Python implementation of a modular neural music-composition system inspired by Wesley R. Elsberry's 1989 master's thesis on constrained melodic composition.

It combines three different network families in one pipeline:

- a Hopfield-Tank note generator
- a back-propagation critic (`Salieri`)
- an ART1 novelty/category module (`Beethoven`)

The repository includes:

- a modern Python codebase with generic network modules and thesis-specific adapters
- legacy thesis source, text, and data files in [`THES/`](./THES)
- timing, entropy, and predictability analysis for generated note sequences
- JSON serialization for learned model state and run reports

## Why This Repo Exists

The original system was implemented in Turbo Pascal on late-1980s hardware under severe memory constraints. That led to pointer-heavy data structures and implementation complexity that obscured what was, architecturally, a strong multi-network design.

This repository keeps the core ideas accessible:

- generic reusable implementations of the underlying network families
- a thesis-faithful composition pipeline built on top of those generic modules
- a practical environment for experimentation, analysis, and historical comparison

## Quick Start

Run a short composition from the thesis data:

```bash
python -m composer_ans --thes-root THES --notes 16
```

Or, if installed as a package:

```bash
triune-cadence --thes-root THES --notes 16
```

Save model state and a run report:

```bash
triune-cadence \
  --thes-root THES \
  --notes 32 \
  --save-salieri salieri.json \
  --save-beethoven beethoven.json \
  --save-report run.json
```

## Sweepable Parameters

The CLI currently exposes a few parameters that are useful for experiments:

- `--object-threshold`
- `--max-attempts-per-note`
- `--art-vigilance`
- `--art-vigilance-decay`

Saved run reports include those parameters along with:

- note sequence
- per-note generation time
- total runtime
- unigram entropy
- first-order conditional entropy
- normalized entropy
- predictability
- redundancy

## Project Layout

Core Python modules live in [`composer_ans/`](./composer_ans):

- generic Hopfield-Tank core: [`composer_ans/hopfield.py`](./composer_ans/hopfield.py)
- generic back-propagation core: [`composer_ans/backprop.py`](./composer_ans/backprop.py)
- generic ART1 core: [`composer_ans/art1.py`](./composer_ans/art1.py)
- thesis-specific wrappers: [`composer_ans/salieri.py`](./composer_ans/salieri.py), [`composer_ans/beethoven.py`](./composer_ans/beethoven.py)
- integrated composition pipeline: [`composer_ans/pipeline.py`](./composer_ans/pipeline.py)
- analysis and reporting: [`composer_ans/analysis.py`](./composer_ans/analysis.py), [`composer_ans/reporting.py`](./composer_ans/reporting.py)

Legacy materials are in [`THES/`](./THES).

## Historical Context

The thesis reports that the integrated system generated 152 notes in about three hours on a 16 MHz 80386-class machine, and in about fifteen hours on an 8088-based machine with an 8087 coprocessor. This Python version can report per-note generation time directly so present-day runs can be compared against those historical figures.

## Development

Run the test suite with:

```bash
pytest -q
```

## Related Repo Notes

The original migration planning artifact is preserved in [`MIGRATION_PLAN.md`](./MIGRATION_PLAN.md).