{"id":15009998,"url":"https://github.com/macr0nerd/project_dilemma","last_synced_at":"2025-04-11T01:02:29.431Z","repository":{"id":213937555,"uuid":"735290987","full_name":"Macr0Nerd/project_dilemma","owner":"Macr0Nerd","description":"The prisoner's dilemma in python","archived":false,"fork":false,"pushed_at":"2025-01-29T10:23:36.000Z","size":21870,"stargazers_count":1,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T04:16:29.868Z","etag":null,"topics":["good-first-issue","goodfirstissue","help-wanted","open-source","prisoner-dilemma","prisoner-dilemma-simulation","prisoners-dilemma","python","python-3","python3","simulation","simulator"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Macr0Nerd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-24T11:26:19.000Z","updated_at":"2025-01-29T10:23:40.000Z","dependencies_parsed_at":"2024-06-12T17:29:46.641Z","dependency_job_id":"75f8420f-4b92-453c-9b0a-b977c48a4581","html_url":"https://github.com/Macr0Nerd/project_dilemma","commit_stats":{"total_commits":50,"total_committers":2,"mean_commits":25.0,"dds":"0.020000000000000018","last_synced_commit":"9d26337cf8ea47c0a658cb62646d37abcd72d9f4"},"previous_names":["macr0nerd/project_dilemma"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macr0Nerd%2Fproject_dilemma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macr0Nerd%2Fproject_dilemma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macr0Nerd%2Fproject_dilemma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macr0Nerd%2Fproject_dilemma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Macr0Nerd","download_url":"https://codeload.github.com/Macr0Nerd/project_dilemma/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247968384,"owners_count":21025824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["good-first-issue","goodfirstissue","help-wanted","open-source","prisoner-dilemma","prisoner-dilemma-simulation","prisoners-dilemma","python","python-3","python3","simulation","simulator"],"created_at":"2024-09-24T19:29:25.220Z","updated_at":"2025-04-11T01:02:29.407Z","avatar_url":"https://github.com/Macr0Nerd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Dilemma\nProject Dilemma is a simulation tool for testing algorithms in the prisoner's dilemma.\nIt provides a standard interface to define both algorithm and simulation classes so that they may be easily tested.\nInspired by [this Veritasium](https://youtu.be/mScpHTIi-kM?si=7pe8XjmjjWLhMup6) video.\n\n## Table of Contents\n* [Installation](#installation)\n  * [PyPi](#pypi)\n  * [Manual](#manual)\n* [Configuration](#configuration)\n  * [Config File Location](#config-file-location)\n  * [Config Format](#config-format)\n  * [Dynamic Imports](#dynamic-imports)\n* [Algorithms](#algorithms)\n* [Simulations](#simulations)\n* [Generational Simulations](#generational-simulations)\n\n## Installation\n### PyPi\n1. `pip install project-dilemma`\n### Manual\n1. Download git repo\n2. Change into repo root directory\n3. `pip install .`\n\n## Configuration\n### Config File Location\nProject Dilemma will automatically try to load the configuration from the user's and system's configuration directories,\nusually set by `$XDG_CONFIG_DIRS`. For most Linux users, this will check `~/.config/project_dilemma` and them somewhere\nin `/etc`.\n\nThis behaviour can be overridden by specifying the `--config` flag to the config file you want to use.\n### Config Format\nProject Dilemma uses the [TOML](https://toml.io/) format for configuration files.\nThis is a human-readable format that is easy to write.\nThe schema has been provided below:\n\n```toml\nsimulation_id = \"name of simulation\"\nalgorithms_directory = \"/path/to/algorithms/\"\nnodes = [ { node_id = \"node_1\", algorithm = { file = \"foo.py\", object = \"Foo\" }, quantity = 11 },\n          { node_id = \"node_2\", algorithm = { file = \"bar/baz.py\", object = \"Baz\" } } ]\nsimulation = { file = \"foobar.py\", object = \"GenerationalFooBar\" }\ngenerational_simulation = { file = \"foobar.py\", object = \"FooBar\" }\nsimulation_arguments = { foo = \"bar\" }\nsimulation_data = \"path/to/round.json\"\nsimulation_data_output = \"path/to/round.json\"\nsimulation_results_output = \"path/to/results.json\"\nsimulations_directory = \"/path/to/simulations/\"\n```\n\n* algorithms_directory\n  * A path to the directory containing the algorithms files\n* generational_simulation\n  * The simulation to run for each generation in a generational simulation as a [Dynamic Import](#dynamic-imports)\n* nodes\n  * An array of tables that specify:\n    * node id\n    * algorithm, as defined in the [Dynamic Imports](#dynamic-imports)\n    * quantity, if not specified then 1 node is assumed\n      * Note: the node index will be appended to the node_id\nsection\n* simulation\n  * The simulation to run as a [Dynamic Import](#dynamic-imports)\n* simulation_id\n  * The name of the simulation\n* simulation_arguments\n  * Arguments to pass into the simulation\n* simulation_data\n  * Path to a JSON file containing previous simulation data\n* simulation_data_output\n  * Path to write the simulation data as a JSON\n* simulation_results_output\n  * Path to write the simulation results\n* simulations_directory\n  * A path to the directory containing additional simulation files\n  * Required for user provided simulations\n\n### Dynamic Imports\nBecause a lot of the objects, such as the algorithms and simulations, can or must be provided by the user, this data\nmust be imported dynamically.\nIn order to easily import these objects without importing every simulation and algorithm, the following format can be\nused to tell the program where to look for the imports:\n\n```toml\n{ file = \"path/to/file\", object = \"ObjectToImport\" }\n```\n\n* file\n  * A path to the file containing the object relative to the associated directory in the config\n  * Required for algorithms and user provided simulations\n* object\n  * The object to import\n    * For builtin simulations, specify the simulation class name here\n\n## Algorithms\nAlgorithms can be defined very easily.\nOnly four things must be done to subclass the Algorithm interface:\n1. Set class name\n2. Set `algorithm_id`\n3. Pass in the mutations to the interface's init (see template for example)\n4. Implement the `decide` function\n5. Set mutations (optional)\n\nThe `decide` function is what the simulation uses to run the algorithm.\nIt accepts a `project_dilemma.interfaces.base.Rounds` object which can be used to get the results of prior rounds, as\nwell as kwargs.\nThe function should return `True` for cooperation, and `False` for defection.\n\n**NOTE**: The BasicSimulation passes the node ID to algorithms via a keyword argument.\nThis is used by algorithms that must be able to identify themselves in prior round data (i.e. FirmButFair).\nIf writing a simulation that does not utilize the BasicSimulation (al the built in ones do), then make sure to pass this\notherwise these algorithms will not work.\nThis is accessible via the `node_id` keyword argument (can be defined as a keyword parameter or via kwargs).\n\nIf you want to add mutations, set the static mutation list *after* defining the class as to avoid circular imports.\n\nA template has been provided in `templates/algorithm_template.py` for ease of use.\n\n## Simulations\nSimulations a more complicated to configure as compared to algorithms.\nYou only need to override the `run_simulation` and `process_simulation` methods, but these are incredibly important.\n\n`run_simulation` returns a `project_dilemma.interfaces.base.Simulations` object that will be used by\n`process_simulation` to get the results.\n\nFor example, the provided standard simulations process the rounds data to calculate scores for each node\nA template can be found in `templates/simulation_template.py`.\n\n### Generational Simulations\nGenerational Simulations are deceptively simple.\nThere is only one function to override: `generational_hook`.\nHowever, this means that all the generational processing must be done in this function.\n\nA template has been provided in `templates/generational_simulation_template.py`.\n\n## License\nCopyright 2023-2025 Gabriele Ron\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n---\nThis project utilizes the [platformdirs](https://github.com/platformdirs/platformdirs) project which is licensed under the MIT License.\nCopyright (c) 2010-202x The platformdirs developers","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacr0nerd%2Fproject_dilemma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacr0nerd%2Fproject_dilemma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacr0nerd%2Fproject_dilemma/lists"}