Voting

Implementations for voting and other social choice behaviors.

Holds basic implementations for:

• VoteAgent: An agent implementing functions needed for voting

• VoteEnvironment: An environment holding basic voting functionality.

• VoteManager: A manager agent for instances of VoteEnvironment when they are slave environments in multi- or distributed environments.

• VoteOrganizer: A class which can initiate voting and compute its results.

It should be noted that only the “true” slave environments, i.e. environments derived from Environment need to have voting behavior implemented (and appropriate voting managers). VoteOrganizer communicates with the “true” slave environments directly without the need of the middle layer environments (multi-environments) or managers in the case of distributed systems.

class creamas.vote.VoteAgent(environment, resources=0, name=None, log_folder=None, log_level=10)

An agent with voting behavior.

Implements three functions needed for voting:

• validate(): Validates a set of candidates returning only the validated candidates.

• vote(): Votes from a set of candidates, i.e. orders them by preference. Returns the ordered list and preferences. Basic implementation orders the candidates using the agent’s evaluate() function.

• add_candidate(): Add candidate artifact to the agent’s environment’s list of current candidates.

add_candidate(artifact)

Add artifact to the environment’s current list of candidates.

validate(candidates)

Validate a list of candidate artifacts.

Candidate validation should prune unwanted artifacts from the overall candidate set. Agent can use its own reasoning to validate the given candidates. The method should return a subset of the given candidates list containing the validated artifacts (i.e. the artifacts that are not pruned).

Note

This basic implementation returns the given candidate list as is. Override this function in the subclass for the appropriate validation procedure.

Parameters

candidates – A list of candidate artifacts

Returns

The validated artifacts, a subset of given candidates

vote(candidates)

Rank artifact candidates.

The voting is needed for the agents living in societies using social decision making. The function should return a sorted list of (candidate, evaluation)-tuples. Depending on the social choice function used, the evaluation might be omitted from the actual decision making, or only a number of (the highest ranking) candidates may be used.

This basic implementation ranks candidates based on evaluate().

Parameters

candidates – list of Artifact objects to be ranked

Returns

Ordered list of (candidate, evaluation)-tuples

class creamas.vote.VoteEnvironment(*args, **kwargs)

An environment implementing functionality needed for voting.

Voting depends largely on a list of candidate artifacts, which are passed down to agents at the time of voting. Candidate artifacts can also be validated by the agents (only returning artifacts that are deemed appropriate, or good enough, by all agents in the environment).

add_candidate(artifact)

Add candidate artifact to the list of current candidates.

clear_candidates()

Remove current candidate artifacts from the environment.

gather_votes(candidates)

Gather votes for the given candidates from the agents in the environment.

Returned votes are anonymous, i.e. they cannot be tracked to any individual agent afterwards.

Returns

A list of votes. Each vote is a list of (artifact, preference) -tuples sorted in a preference order of a single agent.

validate_candidates(candidates)

Validate the candidate artifacts with the agents in the environment.

In larger societies this method might be costly, as it calls each agents’ validate().

Returns

A list of candidates that are validated by all agents in the environment.

property candidates

Current artifact candidates, subject to e.g. agents voting to determine which candidate(s) are added to artifacts.

class creamas.vote.VoteManager(environment)

Manager agent for voting environments.

The class is designed be used in conjunction with VoteEnvironment in multiprocessing and distributed settings.

clear_candidates()

Clear candidates in the managed environment.

This is a managing function for clear_candidates().

async gather_votes(candidates)

Gather votes for the given candidates from the agents in the managed environment.

This is a managing function for gather_votes().

async get_candidates()

Get current candidates from the managed environment.

async validate_candidates(candidates)

Validate the candidates with the agents in the managed environment.

This is a managing function for validate_candidates().

class creamas.vote.VoteOrganizer(environment, logger=None)

A class which organizes voting behavior in an environment.

The organizer can gather_candidates() from the environment, and then gather_votes() for the candidates. Optionally the organizer may validate_candidates() before gathering the votes. After the votes have been collected the organizer may compute_results() of the votes with a given voting method.

The organizer also has gather_and_vote() to do all of the above in one go.

clear_candidates(clear_env=True)

Clear the current candidates.

Parameters

clear_env (bool) – If True, clears also environment’s (or its underlying slave environments’) candidates.

compute_results(voting_method, votes=None, winners=1, **kwargs)

Compute voting results to decide the winner(s) from the votes.

The votes should have been made for the current candidates.

Parameters

• voting_method – A function which computes the results from the votes. Should accept at least three parameters: candidates, votes and number of vote winners. The function should return at least a list of vote winners. See, e.g. vote_mean() or vote_best(). Additional **kwargs are passed down to the voting method.

• votes (list) – A list of votes by which the voting is performed. Each vote should have the same set of artifacts in them. If None the results are computed for the current list of votes.

• winners (int) – The number of vote winners

Returns

list of Artifact objects, the winning artifacts. Some voting methods may also return a score associated with each winning artifact.

Return type

list

gather_and_vote(voting_method, validate=False, winners=1, **kwargs)

Convenience function to gathering candidates and votes and performing voting using them.

Additional **kwargs are passed down to voting method.

Parameters

• voting_method – The voting method to use, see compute_results() for details.

• validate (bool) – Validate gathered candidates before voting.

• winners (int) – The number of vote winners

Returns

Winner(s) of the vote.

gather_candidates()

Gather candidates from the slave environments.

The candidates are stored in candidates, overriding any previous candidates.

gather_votes()

Gather votes from all the underlying slave environments for the current list of candidates.

The votes are stored in votes, overriding any previous votes.

get_managers()

Get managers for the slave environments.

validate_candidates()

Validate current candidates.

This method validates the current candidate list in all the agents in the environment (or underlying slave environments) and replaces the current candidates with the list of validated candidates.

The artifact candidates must be hashable and have a __eq__() implemented for validation to work on multi-environments and distributed environments.

property candidates

Current list of candidates gathered from the environment.

property env

The environment associated with this voting organizer.

property votes

Current list of votes gathered from the environment.

creamas.vote.vote_IRV(candidates, votes, n_winners)

Perform IRV voting based on votes.

Ties are resolved randomly.

Parameters

• candidates – All candidates in the vote

• votes – Votes from the agents

• n_winners (int) – The number of vote winners

creamas.vote.vote_best(candidates, votes, n_winners)

Select the artifact with the single best evaluation as the winner of the vote.

Ties are resolved randomly.

Parameters

• candidates – All candidates in the vote

• votes – Votes from the agents

• n_winners (int) – The number of vote winners

creamas.vote.vote_least_worst(candidates, votes, n_winners)

Select “least worst” artifact as the winner of the vote.

Least worst artifact is the artifact with the best worst evaluation, i.e. its worst evaluation is the best among all of the artifacts.

Ties are resolved randomly.

Parameters

• candidates – All candidates in the vote

• votes – Votes from the agents

• n_winners (int) – The number of vote winners

creamas.vote.vote_mean(candidates, votes, n_winners)

Perform mean voting based on votes.

Mean voting computes the mean preference for each of the artifact candidates from the votes and sorts the candidates in the mean preference order.

Ties are resolved randomly.

Parameters

• candidates – All candidates in the vote

• votes – Votes from the agents

• n_winners (int) – The number of vote winners

creamas.vote.vote_random(candidates, votes, n_winners)

Select random winners from the candidates.

This voting method bypasses the given votes completely.

Parameters

• candidates – All candidates in the vote

• votes – Votes from the agents, which are omitted by randomized voting

• n_winners (int) – The number of vote winners