ecclesia/dist/election/attribution/proportionalBase.d.ts

Framework for political and electoral simulations

import { type Simple } from "../tally";
import { type Attribution, type HasNSeats } from "../attribution";
import { type DisproportionMetric } from "./metrics";
/**
 * An attribution method that allocates seats proportionally
 * to the number of votes received by each party.
 */
export interface Proportional<Party> extends Attribution<Party, Simple<Party>> {
}
/**
 * An specific kind of proportional attribution method,
 * based on a rank-index function, and which
 */
export interface RankIndexMethod<Party> extends Proportional<Party> {
}
/**
 * A function that should be pure : it should not take into account
 * any value other than the arguments passed to it.
 *
 * @param t The fraction of votes received by a candidate
 * @param a The number of seats already allocated to that candidate
 * @returns A value that should be increasing as t rises, and decreasing as a rises.
 * The higher the return value, the more likely the candidate is to receive another seat.
 */
export interface RankIndexFunction {
    (t: number, a: number): number;
}
/**
 * A function creating a fixed-seats, proportional, rank-index attribution method
 * from a rank-index function.
 *
 * The implementation is optimized so as to call rankIndexFunction as few times as possible.
 *
 * Replaces the RankIndexMethod class implementation.
 */
export declare function proportionalFromRankIndexFunction<Party>({ nSeats, rankIndexFunction }: {
    nSeats: number;
    rankIndexFunction: RankIndexFunction;
}): RankIndexMethod<Party> & HasNSeats;
/**
 * Creates a rank-index (proportional) attribution method in which
 * the total number of seats is NOT fixed.
 * Instead, it takes a metric of disproportionality
 * between the entitlements (the votes) and the numbers of seats,
 * and a range of valid number of seats,
 * and the attribution method will return the allocation of seats
 * that minimizes the metric, while respecting the range of valid number of seats.
 *
 * The attribution will only return a 0-seats attribution when the maxNSeats is 0,
 * otherwise, a minNSeats value of 0 will be treated as 1.
 *
 * The metric has a reasonable default.
 *
 * The implementation is still optimized so as to call rankIndexFunction as few times as possible.
 *
 * @param minNSeats The minimum number of seats to be allocated, inclusive.
 * @param maxNSeats The maximum number of seats to be allocated, inclusive.
 */
export declare function boundedRankIndexMethod<Party>({ minNSeats, maxNSeats, rankIndexFunction, metric }: {
    minNSeats: number;
    maxNSeats: number;
    rankIndexFunction: RankIndexFunction;
    metric?: DisproportionMetric<Party>;
}): RankIndexMethod<Party>;
export interface DivisorMethod<Party> extends RankIndexMethod<Party> {
}
/**
 * A function that should be pure.
 * @param k The number of seats already allocated to a party
 * @returns A value that should be increasing as k rises
 */
export interface DivisorFunction {
    (k: number): number;
}
export declare function stationaryDivisorFunction(r: number): DivisorFunction;
export declare function rankIndexFunctionFromDivisorFunction(divisorFunction: DivisorFunction): RankIndexFunction;
/**
 * A function creating a divisor method -
 * one kind of rank-index attribution, itself a kind of proportional attribution.
 */
export declare function proportionalFromDivisorFunction<Party>({ nSeats, divisorFunction }: {
    nSeats: number;
    divisorFunction: DivisorFunction;
}): DivisorMethod<Party> & HasNSeats;