# Monument

A fast, flexible and human-friendly composition generator.

Monument can be thought of as a computer composer: you provide it with a description of what
compositions you want and it generates the best compositions it can, according to your definition
of 'good'.

Monument is currently in an **alpha** state of readiness (see the [known issues](#known-issues)).

_A guide to Monument can be found [here](cli/guide.md)._

## Goals

The ultimate goal of Monument is to **get you compositions that you want to ring, as quickly and
easily as possible**.  Monument should also be correct and performant, but this should be a goal of
all software.

Note that this doesn't necessarily mean generating the perfect composition, or generating _every
possible_ composition.  Monument guarantees neither of these but in return, Monument is **orders of
magnitude faster** than any other composing program I'm aware of (if anyone knows of any faster
generally-available program, then please let me know!).

### Who _isn't_ Monument for?

If you do want to run exhaustive searches or want guaranteed optimal results, then Monument isn't
for you - [SMC](https://github.com/GACJ/smc) is extremely good at exhaustive searching to get
optimal results.  If you want to exhaustively search spliced, I think you need to write your own
generator.  I wish you the best of luck getting results before the inevitable heat death of the
universe.

If you want a graphical user interface, Monument isn't for you (yet).

If you want a generator who's user interface doesn't change often, Monument isn't for you (yet).

## Features

- **FAST**.  Like, really fast.  This specifically means fast at generating compositions _that you
  might want to ring_.
- Easy spliced: Generating spliced is as simple as adding multiple methods.  Various splicing styles
  are supported, such as only changing method at calls.
- Easy multi-parts.  E.g. `part_head = "134265"` will allow `134265` or `142365` (but not `123465`
  or `134256`).
- Short-hands for common things - e.g. `length = "peal"` or `length = "QP"`, or adding runs
  front/back as music:
  ```toml
  [[music]]
  run_lengths = [4, 5, 6, 7, 8]
  ```
- Lots of tuning parameters to make sure Monument understands what you're after:
  - Call weighting to encourage sparse callings.  Give calls a negative score to generate sparse
    callings even if it misses a little bit of music.
  - Add weighting to every row in specific coursing patterns.  For example, encourage
    tenors-together and/or handbell friendly courses.

### Planned/WIP Features

- A GUI to make composition review easier.
- Duffer limits.  E.g. require no more than 3 leads between musical courses.
- Add range requirements to music counts.  E.g. require all 24 5678/8765s.
- Require specific courses/segments.  E.g. require all the `*6578` courses (but not necessarily all
  the 6578s).
- Variable score, to encourage certain types of music in certain places within the composition
- More tuning parameters for e.g. method balance, changes of method, etc.

## Known issues

- Triples methods like Grandsire and Stedman will produce very strange compositions.  Supporting
  these is totally intended, but there are some questions that need answering before either of
  them can fit nicely with Monument's model of ringing.
- Huge memory usage.  This happens due to the way Monument's current search algorithm works.  In
  short, Monument continually keeps track of a big queue of composition prefixes, and repeatedly
  replaces the best prefix with prefixes that are slightly longer.  Storing a large enough queue
  takes a lot of memory, and I haven't implemented a true memory limit yet.  In the mean time,
  adding `-Q <number>` to the end of a command will limit the queue length to `<number>` (the
  default limit is 10,000,000).

## Composing is Hard

Finally, it's worth pointing out that generating compositions is, in general, **really hard** ([NP
hard](https://en.wikipedia.org/wiki/NP-hardness), in fact).  There will always be queries which are
simply too hard for Monument (or any other generator) to complete, so any promise of speed is a
best-effort not a guarantee.

## Under the Hood

If you want to understand how Monument works at a high level, check out the
['Under the Hood'](under-the-hood.md) post.

If you want to understand the code in its gory details (e.g. to contribute), the
[`ARCHITECTURE.md` file](https://github.com/kneasle/ringing/blob/master/monument/README.md)
provides a high-level overview of Monument's code and internal workings.