Package: project-dilemma
Project DilemmaProject Dilemma is a simulation tool for testing algorithms in the prisoner's dilemma.
It provides a standard interface to define both algorithm and simulation classes so that they may be easily tested.
Inspired bythis Veritasiumvideo.Table of ContentsInstallationPyPiManualConfigurationConfig File LocationConfig FormatDynamic ImportsAlgorithmsSimulationsGenerational SimulationsInstallationPyPipip install project-dilemmaManualDownload git repoChange into repo root directorypip install .ConfigurationConfig File LocationProject Dilemma will automatically try to load the configuration from the user's and system's configuration directories,
usually set by$XDG_CONFIG_DIRS. For most Linux users, this will check~/.config/project_dilemmaand them somewhere
in/etc.This behaviour can be overridden by specifying the--configflag to the config file you want to use.Config FormatProject Dilemma uses theTOMLformat for configuration files.
This is a human-readable format that is easy to write.
The schema has been provided below:simulation_id="name of simulation"algorithms_directory="/path/to/algorithms/"nodes=[{node_id="node_1",algorithm={file="foo.py",object="Foo"},quantity=11},{node_id="node_2",algorithm={file="bar/baz.py",object="Baz"}}]simulation={file="foobar.py",object="GenerationalFooBar"}generational_simulation={file="foobar.py",object="FooBar"}simulation_arguments={foo="bar"}simulation_data="path/to/round.json"simulation_data_output="path/to/round.json"simulation_results_output="path/to/results.json"simulations_directory="/path/to/simulations/"algorithms_directoryA path to the directory containing the algorithms filesgenerational_simulationThe simulation to run for each generation in a generational simulation as aDynamic ImportnodesAn array of tables that specify:node idalgorithm, as defined in theDynamic Importsquantity, if not specified then 1 node is assumedNote: the node index will be appended to the node_id
sectionsimulationThe simulation to run as aDynamic Importsimulation_idThe name of the simulationsimulation_argumentsArguments to pass into the simulationsimulation_dataPath to a JSON file containing previous simulation datasimulation_data_outputPath to write the simulation data as a JSONsimulation_results_outputPath to write the simulation resultssimulations_directoryA path to the directory containing additional simulation filesRequired for user provided simulationsDynamic ImportsBecause a lot of the objects, such as the algorithms and simulations, can or must be provided by the user, this data
must be imported dynamically.
In order to easily import these objects without importing every simulation and algorithm, the following format can be
used to tell the program where to look for the imports:{file="path/to/file",object="ObjectToImport"}fileA path to the file containing the object relative to the associated directory in the configRequired for algorithms and user provided simulationsobjectThe object to importFor builtin simulations, specify the simulation class name hereAlgorithmsAlgorithms can be defined very easily.
Only four things must be done to subclass the Algorithm interface:Set class nameSetalgorithm_idPass in the mutations to the interface's init (see template for example)Implement thedecidefunctionSet mutations (optional)Thedecidefunction is what the simulation uses to run the algorithm.
It accepts aproject_dilemma.interfaces.base.Roundsobject which can be used to get the results of prior rounds.
The function should returnTruefor cooperation, andFalsefor defection.If you want to add mutations, set the static mutation listafterdefining the class as to avoid circular imports.A template has been provided intemplates/algorithm_template.pyfor ease of use.SimulationsSimulations a more complicated to configure as compared to algorithms.
You only need to override therun_simulationandprocess_simulationmethods, but these are incredibly important.run_simulationreturns aproject_dilemma.interfaces.base.Simulationsobject that will be used byprocess_simulationto get the results.For example, the provided standard simulations process the rounds data to calculate scores for each node
A template can be found intemplates/simulation_template.py.Generational SimulationsGenerational Simulations are deceptively simple.
There is only one function to override:generational_hook.
However, this means that all the generational processing must be done in this function.A template has been provided intemplates/generational_simulation_template.py.LicenseCopyright 2023 Gabriele RonLicensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.This project utilizes theplatformdirsproject which is licensed under the MIT License.
Copyright (c) 2010-202x The platformdirs developers