# Settability

For the greeter templates, we introduced the concept of _settability_,
represented by a settability score. This is a weighted metric designed
to quantify how easily a crossword grid can be filled with words. It
focuses on three primary factors: _Openness_, _Constraint Density_,
and _Average Word Length_.

The **New Puzzle** greeter ships with templates that are sorted by
settability, from easiest- to hardest-to-fill. We only apply this
score to standard crosswords. In practice cryptic puzzles are much
easier to fill, and the overall concept isn't that useful with those
puzzles.

It is calculated in [tools/grid-extractors/settability.py](https://gitlab.gnome.org/jrb/crosswords/-/blob/master/tools/grid-extractors/settability.py?ref_type=heads)

## Scoring Formula

The score is a weighted sum of three sub-scores, capped at a maximum of 100.00:

 * **Openness (30%):** Calculated as the ratio of normal cells to the
   total grid area. Scores are prioritized for grids with an openness
   factor above 0.75.

 * **Constraint Density (30%):** Measures the "tightness" of the grid
   by comparing the total length of all words to the number of normal
   cells. It favors grids where words are well-integrated but not
   overly restricted.

 * **Average Word Length (40%):** Calculated as the total length of
   all words divided by the total number of words. The score favors
   grids with an average word length significantly higher than 3.5 to
   avoid "choppy" layouts with too many short entries.

## Settability Buckets

To simplify UI categorization, scores are mapped to five discrete
buckets.

 * **Bucket 1:** Score ≤ 38 (Most constrained/difficult to set)
 * **Bucket 2:** Score 39–41
 * **Bucket 3:** Score 42–47
 * **Bucket 4:** Score 48–53
 * **Bucket 5:** Score > 53 (Most open/easiest to set)

## Derivation

These values and percents were determined empirically, by looking at a
large set of puzzles.

