README

主要作者： Julien Boudry
许可： MIT - 如果您喜欢或使用此代码，请打招呼！
贡献：贡献文件
捐赠：₿ bc1q3jllk3qd9fjvvuqy07tawkv7t6h7qjf55fc2gh或Github 赞助页面
您也可以送我一瓶好酒。

Condorcet PHP

介绍 | 文档手册 | API 参考 | 投票方法 | 测试

Condorcet管理选举过程的各个阶段（配置、投票摄入与操作、完整性）并计算结果。它原生提供20多种与优先投票选票兼容的投票方法，包括Condorcet方法、替代投票、STV等。=> 支持的投票方法

使用Condorcet的两种不同方式

一个命令行应用程序，用于快速使用基本功能，无需复杂的技术知识。让您轻松计算选举结果和统计数据。
一个PHP库，您可以将其包含在代码中，以充分利用100%的高级功能（高级操作和配置、扩展和模块化、缓存和高性能模拟、高级输入和输出方法等）。

两种方法都可以在适度硬件上处理高达数亿张选票（或更多）。虽然将其作为库使用将允许更多的配置和控制这种高级使用。

摘要

Condorcet PHP

项目状态和规范

发布说明

所有版本都需要Json和Mbstring扩展（或polyfill）。如果需要激活默认提供的驱动程序以进行大型选举（数十万或更多投票），则建议使用PDO-Sqlite。

支持的投票方法

支持单胜者方法（包括或不包括Condorcet标准）和比例方法。

原生实现的方法的完整列表、它们的选项（变体）和实现选择

原生提供的单胜者方法

单胜者返回所有候选人的完整排名，尽管它们通常被设计为仅指定一个。

确定性

Condorcet / Borda（+ Nauru变体）/ Copeland / Dodgson（2近似值）/ FTPT / 立即决选（选择投票）/ Kemeny–Young / Minimax（+变体）/ 排名对（+变体）/ Schulze（+变体）

彩票

随机投票 / 随机候选人

原生提供的比例方法

旨在选举议会，返回当选候选人的完整排名。

单次可转让选票（STV） / 单次可转让选票的成对结果比较（CPO-STV） / 最高平均值方法（Sainte-Laguë，Jefferson/D'Hondt及其变体） / 最大余数方法（具有不同的配额）

将您自己的投票方法作为模块添加

Condorcet旨在易于通过新算法进行扩展（它们不需要共享相同的命名空间）。

更多解释请参阅此文档
模块骨架：一个用于快速开始开发并遵循最佳实践的模板。

主要功能

管理选举
- 尊重选举周期：注册候选人、投票登记、从许多算法获取结果。
- 排序投票、标记投票、删除投票、模拟部分结果。
- 许多输入类型可用（字符串、Json、对象等）。
- 从Condorcet选举格式（以及导出到）导入，Debian格式，David Hill格式。
- 完整性检查（校验和）
- 支持存储选举（序列化选举对象、导出数据等）
- 一些方法可以在接近最终用户时使用（投票约束、反垃圾邮件检查、解析输入、人性化的结果和统计信息...）
获取选举结果和统计数据
- 获取自然Condorcet胜者、败者、成对、悖论...
- 从高级投票方法获取完整排名
- 从这些方法获取一些其他统计数据
- 强制对所有候选人进行隐式排名（默认）或允许选民不对所有候选人进行排名。
- 对某些投票进行加权，并给予某些选民更多重视。
更加强大
- 所有都是对象，所有都是抽象的（但有许多高级函数和输入类型）。
- 候选人投票是对象，可以同时参与多个选举并动态更改其名称或排名。这允许强大的工具来模拟选举。
- 通过激活外部驱动程序来管理数十亿张选票，在计算阶段存储无限数量的选票（而不是RAM）。默认提供PDO驱动程序，提供SQLite的示例，这是一个允许您设计其他驱动程序的接口。
- 智能缓存系统，允许多次调用计算方法而不出现性能问题。
扩展它！配置它！
- 模块化架构，无需分叉Condorcet PHP即可扩展。只需在自己的命名空间中创建您的模块。
  - 选举、候选人、投票类是可扩展的。
  - 添加您自己的排名算法。
  - 创建您自己的投票约束。
  - 使用您自己的数据存储驱动程序来管理非常大的选举，而无需RAM限制。
- 许多配置选项和方法。

Condorcet PHP 并未设计用于高性能。但它可以处理几乎无限的投票，没有限制或性能下降，它是一个线性且可预测的方案。
没有认证或经过验证的实现可以保证非常高的可靠性。然而，每种投票方法和功能都有许多书面测试。这确保了对结果的高度信心。

将Condorcet用作命令行应用程序

作为命令行应用程序安装

可以从源代码（使用 composer）、PHAR 文件、Docker 镜像（构建或拉取）本地安装。

Condorcet 作为命令行应用程序，安装说明

Condorcet手册 - 命令行

将Condorcet用作PHP库

安装/自动加载

命名空间 \CondorcetPHP\Condorcet 被使用。

您可以使用以下方式安装，您喜欢的方式：Composer / 本地提供的自动加载器 / 任何 PSR-4 兼容的自动加载器。

Condorcet 作为 PHP 库，安装说明

库手册

访问文档书籍

活生生的学习和示例，概述但不是详尽无遗地展示库的用途。

类 & API 参考

方法的精确文档可以以 Markdown 的形式在每次发布的“文档”文件夹中找到。

类 & API 参考

PHP库 - 示例

概述

一般概述 (不是详尽的，但非常精彩。）
高级对象管理

带有Html输出基本示例

具有 HTML 输出的简单和高级脚本示例

具体示例

Condorcet 文档书籍提供了许多代码示例
使用外部数据库驱动管理数百万张选票您自己的驱动程序，或提供的简单 PDO 驱动程序。

性能 & 编码风格注意事项

编码规范

代码在不是不必要地专制或保守且遵循一些额外规则的情况下，非常接近于遵守 PSR-12（仅缺少方法的命名）。代码通过 CS-Fixer 自定义规则和 Laravel Pint 进行检查和修复。

性能

完整的巨大用例，所有投票方法连锁，6 名候选人，2 个席位，1000 张选票（许多具有隐式排名）。
- 内存使用：少于 3M
- 执行时间（JIT 编译后）：少于 160ms
- 执行时间（无 JIT）：少于 250ms

但本质上，因为某些投票方法的设计是慢的，而其他（如 Schulze）则非常快。请查看方法基准测试。

Kemeny-Young案例

1,000 张随机选票。内存消耗来自选票而不是组合。

使用 Kemeny-Young 7 名候选人：~5MB - 10ms
使用 Kemeny-Young 8 名候选人：~6MB - 10ms
使用 Kemeny-Young 9 名候选人：~7MB - 1.1s
使用 Kemeny-Young 10 名候选人：~7MB - 14s
使用 Kemeny-Young 11 名候选人：~8MB - 193s

大规模选举案例

扩展 PHP memory_limit 允许您管理数十万张选票，但可能比外包这些数据（PHP 不喜欢这样做）慢一点，并且不能扩展到无限。

如果您需要管理超过 50,000 张选票的选举。您应该考虑外部化您的数据，Condorcet 提供了一个简单的 PDO 驱动程序，在处理步骤之间将数据存储在 RAM 之外，该驱动程序将其存储到传统的关联数据库系统中，并支持数亿张选票 (或更多)。提供了一个非常简单的 Sqlite 示例，并且很容易激活。

您还可以开发自己的数据存储驱动程序（存储到 NoSQL... 所有您的想象），模块化架构允许您轻松地将其链接。

请查看文档书籍

在现代化机器上的基准测试（linux - x64 - php 8.1 - cli）。

julien-boudry / condorcet

维护者

详细信息