#ai #bellringing #artificial-intelligence


A fast and flexible composition generator

23 releases (13 breaking)

0.14.4 Oct 20, 2023
0.14.2 Sep 9, 2023
0.13.4 Jan 4, 2023
0.12.0 Oct 21, 2022
0.7.0 Mar 28, 2022

#117 in Audio

Download history 25/week @ 2023-08-14 21/week @ 2023-08-21 40/week @ 2023-08-28 66/week @ 2023-09-04 33/week @ 2023-09-11 7/week @ 2023-09-18 8/week @ 2023-09-25 9/week @ 2023-10-02 4/week @ 2023-10-09 81/week @ 2023-10-16 20/week @ 2023-10-23 48/week @ 2023-10-30 9/week @ 2023-11-06 33/week @ 2023-11-13 40/week @ 2023-11-20 104/week @ 2023-11-27

187 downloads per month
Used in monument_cli

MIT license

10K SLoC


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

A guide to Monument can be found here.


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


  • 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:
    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, 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' post.

If you want to understand the code in its gory details (e.g. to contribute), the ARCHITECTURE.md file provides a high-level overview of Monument's code and internal workings.


~80K SLoC