pyRCV2/docs/con.md

# CON file format

pyRCV2 accepts the specification of constraints in a nonstandard file format, referred to as a CON file. The CON format is inspired by the standard [BLT file format](https://yingtongli.me/git/pyRCV2/about/docs/blt.md) used for ballot data.

Suppose there are 7 candidates in the election. An example CON file is as follows:

```
"Gender" "Men" 0 99 2 3 4 6
"Gender" "Women" 2 99 1 5 7
"District" "District 1" 2 2 1 2 3
"District" "District 2" 2 2 4 5 6 7
```

For the purpose of constraints, one or more *categories* are established (in the example, ‘Gender’ and ‘District’). Each category contains one or more *groups*. Within each category, every candidate must be assigned to exactly one group. The constraints are placed on groups, such that a certain minimum number, and a certain maximum number, must be elected from each group.

If there is no minimum for a particular group, specify `0`. If there is no maximum for a particular group, specify any number greater than or equal to the number of candidates in the group.

If there are candidates who do not fit into any group within a particular category, assign those candidates to a placeholder group with a minimum of 0 and a maximum greater than or equal to the number of candidates in the group.

For example, the line `"Gender" "Men" 0 99 2 3 4 6` means that within the ‘Gender’ category ‘Men’ group, a minimum of 0 candidates and a maximum of 99 candidates can be elected (i.e. there are no constraints). The candidates in the ‘Men’ group are candidates 2, 3, 4 and 6 (in the order listed in the BLT file).

The remaining lines indicate that a minimum of 2 women must be elected (with a maximum of 99, i.e. no maximum), and exactly 2 candidates must be elected from each of districts 1 and 2.

Every line describes one group within a category, and every group must be described on its own line.