Stars: 114
Forks: 13
Pull Requests: 69
Issues: 83
Watchers: 11
Last Updated: 2023-08-14 10:06:22
Command line application and PHP library, providing an election engine with a high-level interface. Native support 20+ voting methods, easy to extend. Support simple elections with ease or billions of votes in low resource environment. Intensively tested and highly polyvalent.
License: MIT License
Languages: PHP, Dockerfile, Shell
Main Author: Julien Boudry
License: MIT - Please say hello if you like or use this code!
Contribute: Contribute File
Donation: ₿ bc1q3jllk3qd9fjvvuqy07tawkv7t6h7qjf55fc2gh or Github Sponsor Page
You can also offer me a bottle of good wine.
Presentation | Documentation Book | API References | Voting Methods | Tests
Condorcet manages the stages of an electoral process (configuration, votes ingestion & manipulation, integrity) and calculates the results. It offers natively the implementation of more than 20 voting methods compatible with preferential voting ballots, including Condorcet methods, Alternative Voting, STV, and many others. => Supported Voting Methods
Two different ways to use Condorcet:
Both approaches can handle up to hundreds of millions of votes (or more) on modest hardware. Although using it as a library will allow more configuration and control over this advanced usage.
Version | PHP Requirements | State | Support |
---|---|---|---|
4.5 | 8.2 | Stable | ✔ support provided |
4.2 | 8.1 | Old Stable | ✔ support provided |
3.x | 8.1 | Old Stable | ❌ not any support |
2.2 | 7.4 | Old Stable | ❌ support requiring some bait |
2.0 | 7.1 | Old Stable | ❌ not any support |
1.0 | 5.6 | Old Stable | ❌ not any support |
0.9x | 5.5 | Old Stable | ❌ ℹ Since v0.90, you should consider then it's a new project (api, engine). |
0.14 | 5.5 | Old Stable | ❌ ready for the museum |
All versions require Json and Mbstring extensions (or polyfill). Pdo-Sqlite is recommended if you need to activate the default provided driver for bigs elections (hundred of thousands of votes or more)
Support both single-winner methods (with or without the Condorcet criterion) and proportional methods.
Complete list of natively implemented methods, their options (variants), and implementation choices
Single Winner returns a full ranking of all candidates, even though they are generally more designed to designate only one.
Condorcet / Borda (+ Nauru variant) / Copeland / Dodgson (2 Approximations) / FTPT / Instant-runoff (alternative vote) / Kemeny–Young / Minimax (+ variants) / Ranked Pairs (+ variants) / Schulze (+ variants)
Random Ballot / Random Candidates
Designed for electing assembly, return a full ranking of elected candidates.
Single Transferable Vote (STV) / Comparison of Pairs of Outcomes by the Single Transferable Vote (CPO-STV) / Highest Averages Methods (Sainte-Laguë, Jefferson/D'Hondt, and variants) / Largest Remainder Methods (with different quotas)
Condorcet is designed to be easily extensible with new algorithms (they don't need to share the same namespace).
Condorcet PHP is not designed for high performance. But can handle virtually unlimited voting without limit or degrading performance, it's a linear and predictable scheme.
And has no certification or proven implementation that would guarantee a very high level of reliability. However, there are many written tests for each voting method and feature. This ensures an excellent level of confidence in the results.
Can be installed natively from source (with composer), from PHAR file, from Docker image (build or pull).
Condorcet as a command line application, installation instructions
Namespace \CondorcetPHP\Condorcet
is used.
Can be installed as you prefer with: Composer / Natively provided autoloader / Any PSR-4 compatible autoloader.
Living and learning examples, giving an overview but not exhaustive of the possibilities of the library.
The precise documentation of methods can be found in the form of Markdown in the "Documentation" folder for each release.
The code is very close to the respect of PSR-12 (lacks only the naming of methods) when it is not unnecessarily authoritarian or conservative and follows some additional rules. Code is checked and fixed with CS-Fixer custom rules through Laravel Pint.
But essentially because some voting methods are slow by design and others (like Schulze) are very fast. Have a look on methods benchmarks.
1 000 randoms votes. Memory consumption comes from votes more than combinations.
Extending PHP memory_limit allows you to manage hundreds of thousands of votes, but it can be a bit slower than outsourcing this data (PHP doesn't like that) and it's not extensive to infinity.
If you need to manage an election with more than 50 000 votes. You should consider externalizing your data, Condorcet provides a simple PDO driver to store data outside RAM between processing steps, this driver stores it into a classical relational database system, and it supports hundreds of millions of votes (or more). A very simple example with Sqlite is provided and very easy to activate.
You can also develop your homemade datastore driver (to store into NoSQL... all your fantasy), the modular architecture allows you to link it easily.
Have a look at the documentation book
Benchmark on a modern machine (linux - x64 - php 8.1 - cli).