kneasle / ringing

Monument, BellFrame and other Rusty change ringing projects.

Ringing

A single repository containing all my Rust projects related to change ringing. More info about change ringing can be found here, though if you're not into ringing this whole repo probably won't make much sense...

Projects

• Monument: A fast, flexible and human-friendly composing engine
• Jigsaw (yet to be moved here): A visual tool for experimenting with compositions

Libraries

• BellFrame: A 'standard library' for change ringing, shared between all projects.
• utils: Small utilities which aren't specific to ringing. Mostly extensions to the standard library, with few or no dependencies. Also shared between projects.

---

As far as cargo/rust is concerned, this repository is one single workspace consisting of many separate crates. Each project/library lives in its own directory and may correspond to multiple Rust crates. Having all of these in the same repository ensures that all code is kept synchronised, and CI doesn't have to worry about dependency shenanigans.

All projects are under the MIT license.

ringing's Issues

Is there an idiot's guide?

I would love to use this however to search for compositions, but I have only managed to get it installed so far and got rather lost after that.

Is there a 'Dummies' guide to writing the code required and executing it to search for a comp?

Many thanks.

Todo list

Monument (CLI/lib)

Bugs

• In music patterns, count and count_each cause a todo!() panic (found by @simon-bond).
• When deduplicating links, always choose the one with the highest score (IIRC Monument currently chooses non-deterministically)
• Prevent user from inputting reversed ranges (e.g. { min = 1250, max = 1200 })
• Non-duffers and multi-parts play really badly together
  • Contiguous duffers don't work over the part head
  • Contiguous duffer distances need to be computed for each part
• splice_style = "calls" not working for lead-wise comps
• splice_style = "calls" still generating splices over part-heads
• Count method splices over part-heads
• Occasional false comps (#72)
• Rounds and backrounds count as n-bell runs from both front and back (and therefore get double counted). Considered not a bug (but a feature 😄!)
• Make multiple start/end locations work with multi-parts (currently crashes)

Features

• Proper support for positional calls
• Allow specifying method ranges by percentage of length range
• Mixed stage splicing
• Uneven but still group multi-parts (e.g. 12{34,43}{56,65} or 1342, 132)
• Print stats on a fixed time interval, rather than every 100K iterations
• Better shorthand generation
• Add weights to repeating the same place bell multiple times
• Print warnings again after all compositions
• Specify start strokes for each start index individually
• Allow graph size limit to be set in the TOML files (because only specific files will require a larger size limit, and it seems dumb to only be able to set it as a CLI arg)
• Smarter algorithm for computing method balance
• Sort comps by absolute music?
• Add bobs_only and singles_only
• Calculate/require ATW
• Print final comp list even for ctrl-C
• Limit on graph size
• Default music scoring
• Make calling_bell a global option
• Add weights to changes of method
• Add column headers for the composition output
• Display music breakdown in comp output
• Music type presets for (e.g. music = [{ preset = "near misses" }]):
  • 5678 combinations
  • Near misses
  • CRUs

UX

• Show maxest max len value reached if a run fails.
• Improve docs
  • Host them as a proper site
  • Add dedicated examples
  • Add runnable/testable examples for each parameter
  • Split parameter reference into its own page
• Rename course_heads to courses and ch_weights to course_weights
• Switch allow_false to require_truth
• Remove call.debug_symbol and auto-generate it for bobs
• Rename lead_location(s) to lead_label(s) or just label(s)
• Print header line every 50 compositions

Optimisation

• Determine which ordering of successor links produces the best comps (currently they're assigned non-deterministically based on the order of links in a HashMap).
• Run graph optimisation passes until the last pass that reduced graph size is run again (instead of waiting for a full round of optimisations)
• For multiparts, remove graph any start/ends which don't share a RowIdx with a corresponding end/start.

Refactoring

• Make Count take an index type parameter (i.e. Count<MusicTypeIdx> and Count<MethodIdx> to prevent mixing of counts of method rows/music types)
• Make OptRange generic
• Identify Chunks by their range rather than their head?
• Rewrite graph generation:
  • Remove Layout, and generate a Graph directly from a Query
  • Remove the distinction between lead- and course-wise compositions
  • Allow CHs to be specified for lead-wise compositions
  • Remove the CH incompatibility check, and have chunks labelled by the first matching CH in the list
  • Make all ends 0-length. I.e. 0-length end chunks are no longer a special case
• Add abstraction for PartHeadGroups
• Exclusively use {PerPart,Total}Length (i.e. impl Add/Mul<usize>)
• Explicit memory limit (#20, blocked on having a benchmark suite/runner)
• Remove serde dependency from monument/lib?
• Rename bellframe::Regex to bellframe::Pattern

Warnings/suggestions:

• Loading an existing method by place notation
• Course heads which are unreachable/never appear in the graph
• Add warning that Grandsire and Stedman won't work very well
• Recommend {bobs,singles}_only if user gives massive negative weight to either of them
• Using method_count with only one method? This may be useful, and will produce explicitly errors rather than silently running for ages on an impossible task.
• Suggest compatible course heads for resolvable conflicts. Incompatible course heads no longer cause an error

Errors:

• Unreachable part heads (e.g. out-of-course PHs in bobs-only comps)
• Duplicate methods
• Explicit error when no comps are possible because the graph is empty
• Add check & error for setting CH masks that aren't preserved by the part heads
• Add error for duplicate call names
• Better messages
• Statically prove when lengths are impossible (e.g. asking for a 5080 of whole-course Royal)
• Statically prove which method counts are actually possible
• Clearly impossible method bounds (e.g. where the total max method < min row count, and vice versa)

Graph optimisations

• Merge nodes with no splice which must be adjacent
• Remove links between mutually false nodes
• Remove links between chunks which contribute too many method counts (also will remove any chunks with too much method count by disconnecting them from the rest of the graph)
• Make the point of graph optimisation to minimise (#nodes, #links, Reverse(#required))

Testing

• Run examples in the guide as integration tests
• Remove ANSI escape codes from error messages so (a) the tests work on Windows and (b) the error message diffs actually render correctly
• Make all tests deterministic
• Make test harness understand:
  • Missing tests
  • Moved tests
• Create benchmark suite and runner

BellFrame

• Remove dedicated place notation types (using them only for conversions to/from Blocks or Rows).
  • Implement jump changes
• Make Row::closure{,_from_rounds} return an Iterator rather than a Vec
• Full docs/examples coverage
• Method library:
  • Split into its own crate?
  • Link a copy of the CC library into the binary, so internet access isn't required on first startup
  • Use better compression/a binary format for storing the methods
• Fix unsoundness issues:
  • Enforce Mask invariants
  • Give Regexs a Stage
  • Enforce Regex invariants
• Switch to making Bell/Stage/etc. be newtypes over u8 (reducing memory usage, improving cache performance, potential for SIMD)
• Remove type Block = AnnotBlock<()> and rename AnnotBlock to Block

Add explicit memory limit

Currently, memory usage is regulated by the queue length limit (using the -Q CLI arg) but memory limit is roughly O(queue len * graph size) so larger graphs cause larger memory usage. It'd be nice to be able to give an explicit memory bound and have Monument work out the rest.

Add plain calls for duplicate positions

If you splice two methods who's lead ends aren't powers of each other (e.g. Original and Plain Bob) then it is possible to get the same calling position twice in a course without the result running false. These calling positions must be disambiguated using plain leads. Currently Monument doesn't emit any plain leads.

Phantom method splice

Sometimes Monument inserts a phantom method splice at the end of the composition (the only time it doesn't is if you finish on the first method defined in the methods field). This happens because the 0-length end nodes are always assigned method #0, thus creating a phantom splice. This is, unfortunately, really difficult to fix with the intermediate Layout type because it assumes that every instance of a given call must be given the same weight. Probably the least hard fix is to defer the weight computation until after the graph has been generated (music counting already works like this).

libssl.so.1.1 missing

I just rebuilt my win11 machine / WSL / Ubuntu 22.04LTS.

I pulled down the current build for momument but it failed with missing library. libssl.slo.1.1

This seems to be known issue, you can fix it with

wget http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb

Might be worth adding to the installation instructions.

Occasional false comps

Sometimes Monument generates a false composition, for example for this input:

length = "Peal"
methods = [
    "Cambridge Surprise Major",
    "Yorkshire Surprise Major",
    "Superlative Surprise Major",
    "Bristol Surprise Major",
    { title = "Cornwall Surprise Major", shorthand = "W" },
    { title = "Lessness Surprise Major", shorthand = "E" },
    "London Surprise Major",
]
music_file = "music-8.toml"
base_calls = "near"
bob_weight = -4
single_weight = -4
num_comps = 20
part_head = "14236578"
course_heads = ["*78", "*7856"]
method_count = { min = 500, max = 900 }

we get the following false comp: B[sH]BEL[B]W[V]EEW[sM]B[sM]WEW[sV]S[B]SC[H]YCS[sM]YYLC[B]SY[sH]LC[sW]B