{"id":15553573,"url":"https://github.com/varnio/fedsim","last_synced_at":"2025-10-12T18:30:18.529Z","repository":{"id":37491289,"uuid":"503834295","full_name":"varnio/fedsim","owner":"varnio","description":"A generic Federated Learning simulator!","archived":false,"fork":false,"pushed_at":"2023-03-03T15:11:47.000Z","size":17250,"stargazers_count":7,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-16T20:19:26.737Z","etag":null,"topics":["deep-learning","distributed-learning","federated-learning","neural-networks","optimization","privacy","pytorch","research","simulator"],"latest_commit_sha":null,"homepage":"http://fedsim.varnio.com","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/varnio.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst"}},"created_at":"2022-06-15T16:02:10.000Z","updated_at":"2023-04-23T08:26:21.000Z","dependencies_parsed_at":"2024-01-17T07:07:11.118Z","dependency_job_id":"57044577-c277-479b-b238-2d4ef7529041","html_url":"https://github.com/varnio/fedsim","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varnio%2Ffedsim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varnio%2Ffedsim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varnio%2Ffedsim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varnio%2Ffedsim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varnio","download_url":"https://codeload.github.com/varnio/fedsim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236261751,"owners_count":19120767,"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":["deep-learning","distributed-learning","federated-learning","neural-networks","optimization","privacy","pytorch","research","simulator"],"created_at":"2024-10-02T14:38:42.720Z","updated_at":"2025-10-12T18:30:15.711Z","avatar_url":"https://github.com/varnio.png","language":"Python","funding_links":[],"categories":["federated learning framework"],"sub_categories":["table"],"readme":"FedSim\n======\n\n.. image:: https://github.com/varnio/fedsim/actions/workflows/github-actions.yml/badge.svg\n    :alt: GitHub Actions Build Status\n    :target: https://github.com/varnio/fedsim/actions\n\n.. image:: https://img.shields.io/pypi/v/fedsim.svg\n    :alt: PyPI Package latest release\n    :target: https://pypi.org/project/fedsim\n\n.. image:: https://readthedocs.org/projects/fedsim/badge/?version=stable\n    :target: https://fedsim.readthedocs.io/en/latest/?badge=stable\n\n.. image:: https://img.shields.io/pypi/wheel/fedsim.svg\n    :alt: PyPI Wheel\n    :target: https://pypi.org/project/fedsim\n\n.. image:: https://img.shields.io/pypi/pyversions/fedsim.svg\n    :alt: Supported versions\n    :target: https://pypi.org/project/fedsim\n\n.. image:: https://img.shields.io/pypi/implementation/fedsim.svg\n    :alt: Supported implementations\n    :target: https://pypi.org/project/fedsim\n\n.. image:: https://codecov.io/gh/varnio/fedsim/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/varnio/fedsim\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/psf/black\n\n.. image:: https://badges.gitter.im/varnio/community.svg\n    :alt: Gitter\n    :target: https://gitter.im/varnio/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\n\n\nFedSim is a comprehensive and flexible Federated Learning Simulator! It aims to provide the researchers with an easy to develope/maintain simulator for Federated Learning.\nSee documentation at `here \u003chttps://fedsim.varnio.com/en/latest/\u003e`_!\n\n\nInstallation\n============\n\n.. code-block:: bash\n\n   pip install fedsim\n\nThat's it! You are all set!\n\n-------------------\n\n\nDesign Architecture\n===================\n\n.. image:: https://raw.githubusercontent.com/varnio/fedsim/3387a994664853c599094a72b342b8f7f3dba0f2/docs/source/_static/arch.svg\n    :width: 90%\n\n\n\nCLI\n=====\n\nMinimal example\n---------------\n\nFedsim provides powerful cli tools that allow you to focus on designing what is truly important.\nSimply enter the following command to begin federatively training a model.\n\n.. code-block:: bash\n\n    fedsim-cli fed-learn\n\nThe \"MNIST\" dataset is partitioned on 500 clients by default, and the FedAvg algorithm is used to train a minimal model with two fully connected layers.\nA text file is made that descibes the configuration for the experiment and a summary of results when it is finished. Additionally, a tensorboard log file is made to monitor the scores/metrics of the training.\nThe directory that these files are stored is (reconfigurable and is) displayed while the experiment is running.\n\n.. image:: https://github.com/varnio/fedsim/blob/main/docs/source/_static/examples/one_line_train.gif?raw=true\n\nHooking scores to cli tools\n---------------------------\n\nIn case you are interested in a certain metric you can make a query for it in your command.\nFor example, lets assume we would like to test and report:\n* the accuracy score of the global model on global test dataset both every 21 rounds and every 43 rounds.\n* the average accuracy score of the local models every 15 rounds.\nHere's how we modify the above command:\n\n.. code-block:: bash\n\n    fedsim-cli fed-learn \\\n        --global-score Accuracy score_name:acc21 split:test log_freq:21 \\\n        --global-score Accuracy score_name:acc43 split:test log_freq:43 \\\n        --local-score Accuracy split:train log_freq:15\n\n.. image:: https://github.com/varnio/fedsim/blob/main/docs/source/_static/examples/add_metrics.gif?raw=true\n\n.. image:: https://github.com/varnio/fedsim/blob/main/docs/source/_static/examples/tb_ex.png?raw=true\n\nCheck `Fedsim Scores Page \u003chttps://fedsim.varnio.com/en/latest/reference/fedsim.scores.html\u003e`_ for the list of all other scores like Accyracy or define your custom score.\n\nChanging the Data\n-----------------\n\nData partitioning and retrieval is controlled by a ``DataManager`` object. This object could be controlled through `-d` or `--data-manager` flag in most cli commands.\nIn the following we modify the arguments of the default ``DataManager`` such that ``CIFAR100`` is partitioned over 1000 clients.\n\n.. code-block:: bash\n\n    fedsim-cli fed-learn \\\n        --data-manger BasicDataManager dataset:cifar100 num_partitions:1000 \\\n        --num-clients 1000 \\\n        --model SimpleCNN2 num_classes:100 \\\n        --global-score Accuracy split:test log_freq:15\n\nNotice that we also changed the model from default to ``SimpleCNN2`` which by default takes 3 input channels.\nYou can learn about existing data managers at `data manager documentation \u003chttps://fedsim.varnio.com/en/latest/reference/fedsim.distributed.data_management.html\u003e`_ and Custom data managers at `this guide to make Custom data managers \u003chttps://fedsim.varnio.com/en/latest/user/data_manager.html\u003e`_.\n\n.. note::\n\n    Arguments of the constructor of any component (rectangular boxes in the image of design architecture) could be given in `arg:value` format following its name (or `path` if a local file is provided).\n    Among these component, the algorithm is special, in that the arguments are controlled internally. The only arguments of the algorithm object that could be directly controlled in your commands is the algorithm specific ones (mostly hyper-parameters).\n    Examples:\n\n    .. code-block:: bash\n\n        fedsim-cli fed-learn --algorithm AdaBest mu:0.01 beta:0.6 ...\n\n\nFeed CLI with Customized Components\n-----------------------------------\n\nThe cli tool can take a locally defined component by ingesting its path.\nFor example, to automatically include your custom algorithm by the a command of the cli tool, you can place your class in a python file and pass the path of the file to `-a` or `--algorithm` option (without .py) followed by colon and name of the algorithm definition (class or method).\nFor instance, if you have algorithm `CustomFLAlgorithm` stored in a `foo/bar/my_custom_alg.py`, you can pass `--algorithm foo/bar/my_custom_alg:CustomFLAlgorithm`.\n\n\n.. code-block:: bash\n\n        fedsim-cli fed-learn --algorithm foo/bar/my_custom_alg_file:CustomFLAlgorithm mu:0.01 ...\n\nThe same is possible for any other component, for instance for a Custom model:\n\n.. code-block:: bash\n\n        fedsim-cli fed-learn --model foo/bar/my_model_file:CustomModel num_classes:1000 ...\n\n\nMore about cli commands\n-----------------------\n\nFor help with cli check `fedsim-cli documentation \u003chttps://fedsim.varnio.com/en/latest/clidoc/index.html\u003e`_ or read the output of the following commands:\n\n.. code-block:: bash\n\n   fedsim-cli --help\n   fedsim-cli fed-learn --help\n   fedsim-cli fed-tune --help\n\nPython API\n==========\n\nFedsim is shipped with some of the most well-known Federated Learning algorithms included. However, you will most likely need to quickly develop and test your custom algorithm, model, data manager, or score class.\nFedsim has been designed in such a way that doing all of these things takes almost no time and effort. Let's start by learning how to import and use Fedsim, and then we'll go over how to easily modify existing modules and classes to your liking.\nCheck the following basic example:\n\n.. code-block:: python\n\n    from logall import TensorboardLogger\n    from fedsim.distributed.centralized.training import FedAvg\n    from fedsim.distributed.data_management import BasicDataManager\n    from fedsim.models import SimpleCNN2\n    from fedsim.losses import CrossEntropyLoss\n    from fedsim.scores import Accuracy\n\n    n_clients = 1000\n\n    dm = BasicDataManager(\"./data\", \"cifar100\", n_clients)\n    sw = TensorboardLogger(path=None)\n\n    alg = FedAvg(\n        data_manager=dm,\n        num_clients=n_clients,\n        sample_scheme=\"uniform\",\n        sample_rate=0.01,\n        model_def=partial(SimpleCNN2, num_channels=3),\n        epochs=5,\n        criterion_def=partial(CrossEntropyLoss, log_freq=100),\n        batch_size=32,\n        metric_logger=sw,\n        device=\"cuda\",\n    )\n    alg.hook_local_score(\n        partial(Accuracy, log_freq=50),\n        split='train,\n        score_name=\"accuracy\",\n    )\n    alg.hook_global_score(\n        partial(Accuracy, log_freq=40),\n        split='test,\n        score_name=\"accuracy\",\n    )\n    report_summary = alg.train(rounds=50)\n\nSide Notes\n==========\n* Do not use double underscores (`__`) in argument names of your customized classes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvarnio%2Ffedsim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvarnio%2Ffedsim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvarnio%2Ffedsim/lists"}