Add readme.
parent
a19527d9d6
commit
c36eb12997
@ -0,0 +1,106 @@
|
|||||||
|
|
||||||
|
## Deliberate: A deliberation and voting module for goblins
|
||||||
|
|
||||||
|
This module provides deliberation tools for the
|
||||||
|
[Guile](https://www.gnu.org/software/guile/) scheme version of
|
||||||
|
[Goblins](https://spritely.institute/goblins/).
|
||||||
|
Currently, this module provides ranked-chioce ballots and two ranked-choice
|
||||||
|
voting systems: Instant-Runoff Voting, and the Borda count method.
|
||||||
|
These features should be considered experimental.
|
||||||
|
|
||||||
|
## Using Deliberate
|
||||||
|
First, download the repository to a location in the Guile load path,
|
||||||
|
then the module may be imported as usual:
|
||||||
|
|
||||||
|
(use-modules (deliberate))
|
||||||
|
|
||||||
|
Note that code must be run in a goblins vat:
|
||||||
|
|
||||||
|
(use-modules (goblins)
|
||||||
|
(goblins vrun))
|
||||||
|
|
||||||
|
(define a-vat (spawn-vat))
|
||||||
|
(define-vat-run a-run a-vat)
|
||||||
|
|
||||||
|
### Creating a deliberation
|
||||||
|
A deliberation provides discussion and voting related to a particular topic.
|
||||||
|
To create a deliberation, spawn a `^deliberation` object and pass it the topic:
|
||||||
|
|
||||||
|
(define deliberation (a-run
|
||||||
|
(spawn ^deliberation "Power Generator"))
|
||||||
|
|
||||||
|
The topic can be read and set using the `topic` and `set-topic` message:
|
||||||
|
|
||||||
|
(a-run ($ deliberation 'topic))
|
||||||
|
;; => "Power Generator
|
||||||
|
|
||||||
|
(a-run ($ deliberation 'set-topic "Infrastructure"))
|
||||||
|
(a-run ($ deliberation 'topic))
|
||||||
|
;; => "Infrastructure
|
||||||
|
|
||||||
|
### Adding a vote
|
||||||
|
Each deliberation object may contain multiple votes. Votes are added with the
|
||||||
|
`add-vote` message with a question to be voted on:
|
||||||
|
|
||||||
|
(define vote (a-run
|
||||||
|
($ deliberation 'add-vote "What type of power should we use?"))
|
||||||
|
|
||||||
|
For it to be useful, the vote also needs a number of alternatives that can be
|
||||||
|
voted on:
|
||||||
|
|
||||||
|
(a-run
|
||||||
|
($ vote 'add-alternative "solar")
|
||||||
|
($ vote 'add-alternative "wind")
|
||||||
|
($ vote 'add-alternative "hydro"))
|
||||||
|
|
||||||
|
The list of votes can be fetched with the `votes` message.
|
||||||
|
|
||||||
|
### Creating ballots
|
||||||
|
Once a vote object has been created, ballot objects can be created and
|
||||||
|
distributed:
|
||||||
|
|
||||||
|
(define alice-ballot (a-run ($ vote 'add-ballot)))
|
||||||
|
|
||||||
|
### Using a ballot to vote
|
||||||
|
The question and alternatives can be fetched using the `question` and
|
||||||
|
`alternatives` messages:
|
||||||
|
|
||||||
|
(a-run ($ alice-ballot 'question))
|
||||||
|
;; "What type of power should we use?
|
||||||
|
|
||||||
|
(a-run ($ alice-ballot 'alternatives))
|
||||||
|
;; ("hydro" "wind" "solar")
|
||||||
|
|
||||||
|
Votes are cast by passing a function that maps alternatives to their rank
|
||||||
|
(with 1 being the highest):
|
||||||
|
|
||||||
|
(define (cast-vote alts)
|
||||||
|
(map (lambda (alt)
|
||||||
|
(cond
|
||||||
|
((string=? "wind" alt) 1)
|
||||||
|
((string=? "solar" alt) 2)
|
||||||
|
((string=? "hydro" alt) 3)))
|
||||||
|
alts))
|
||||||
|
(a-run ($ alice-ballot 'update-vote cast-vote))
|
||||||
|
|
||||||
|
While this interface may seem cumbersome, it ensures consistency between the
|
||||||
|
available alternatives and those being voted on. Votes can be checked using
|
||||||
|
the `ranking` message:
|
||||||
|
|
||||||
|
(a-run ($ alice-ballot 'ranking))
|
||||||
|
;; => ("solar" "wind" "hydro")
|
||||||
|
|
||||||
|
### Calculating winners
|
||||||
|
Vote winners can be calculated using `irv-winner` or `borda-winner`:
|
||||||
|
|
||||||
|
(a-run ($ vote 'irv-winner))
|
||||||
|
;; => ("wind")
|
||||||
|
|
||||||
|
Note that these messages return a list which may include multiple alternatives
|
||||||
|
in the case of a tie.
|
||||||
|
|
||||||
|
An overall social preference ranking can also be calculated using
|
||||||
|
`irv-preference` and `borda-preference`:
|
||||||
|
|
||||||
|
(a-run ($ vote 'borda-preference))
|
||||||
|
;; => (("wind") ("solar") ("hydro"))
|
Loading…
Reference in New Issue