Merge branch 'master' into feature/SK-823

.readthedocs.yaml

@@ -11,5 +11,5 @@ sphinx:
 python:
   install:
     - method: pip
-      path: ./fedn
+      path: .
     - requirements: docs/requirements.txt

docs/conf.py

@@ -4,31 +4,31 @@
 import sphinx_rtd_theme  # noqa: F401
 
 # Insert path
-sys.path.insert(0, os.path.abspath('../fedn'))
+sys.path.insert(0, os.path.abspath(".."))
 
 # Project info
-project = 'FEDn'
-copyright = '2021, Scaleout Systems AB'
-author = 'Scaleout Systems AB'
+project = "FEDn"
+copyright = "2021, Scaleout Systems AB"
+author = "Scaleout Systems AB"
 
 # The full version, including alpha/beta/rc tags
-release = '0.9.1'
+release = "0.9.2"
 
 # Add any Sphinx extension module names here, as strings
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    'sphinx_rtd_theme',
-    'sphinx_code_tabs'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "sphinx_code_tabs"
 ]
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
@@ -39,31 +39,31 @@
 exclude_patterns = []
 
 # The theme to use for HTML and HTML Help pages.
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 html_theme_options = {
-    'logo_only': True,
+    "logo_only": True,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'fedndocs'
+htmlhelp_basename = "fedndocs"
 
 # If defined shows an image instead of project name on page top-left (link to index page)
-html_logo = '_static/images/scaleout_logo_flat_dark.svg'
+html_logo = "_static/images/scaleout_logo_flat_dark.svg"
 # FEDn logo looks ugly on rtd theme
 
-html_favicon = 'favicon.png'
+html_favicon = "favicon.png"
 
 # Here we assume that the file is at _static/custom.css
 html_css_files = [
-    'css/elements.css',
-    'css/text.css',
-    'css/utilities.css',
+    "css/elements.css",
+    "css/text.css",
+    "css/utilities.css",
 ]
 
 # LaTeX elements
@@ -89,32 +89,32 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'fedn.tex', 'FEDn Documentation',
-     'Scaleout Systems AB', 'manual'),
+    (master_doc, "fedn.tex", "FEDn Documentation",
+     "Scaleout Systems AB", "manual"),
 ]
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'fedn', 'FEDn Documentation',
+    (master_doc, "fedn", "FEDn Documentation",
      [author], 1)
 ]
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'fedn', 'FEDn Documentation',
-     author, 'fedn', 'One line description of project.',
-     'Miscellaneous'),
+    (master_doc, "fedn", "FEDn Documentation",
+     author, "fedn", "One line description of project.",
+     "Miscellaneous"),
 ]
 
 # Bibliographic Dublin Core info.
 epub_title = project
 
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {"https://docs.python.org/": None}
 
-pygments_style = 'sphinx'
+pygments_style = "sphinx"

examples/FedSimSiam/.dockerignore

@@ -0,0 +1,4 @@
+data
+seed.npz
+*.tgz
+*.tar.gz

examples/FedSimSiam/.gitignore

@@ -0,0 +1,6 @@
+data
+*.npz
+*.tgz
+*.tar.gz
+.fedsimsiam
+client.yaml

examples/FedSimSiam/README.rst

@@ -0,0 +1,125 @@
+FEDn Project: FedSimSiam on CIFAR-10
+------------------------------------
+
+This is an example FEDn Project that runs the federated self-supervised learning algorithm FedSimSiam on 
+the CIFAR-10 dataset. This is a standard example often used for benchmarking. To be able to run this example, you 
+need to have GPU access. 
+
+   **Note: We recommend all new users to start by following the Quickstart Tutorial: https://fedn.readthedocs.io/en/stable/quickstart.html** 
+
+Prerequisites
+-------------
+
+-  `Python 3.8, 3.9, 3.10 or 3.11 <https://www.python.org/downloads>`__
+-  `A FEDn Studio account <https://fedn.scaleoutsystems.com/signup>`__   
+-  Change the dependencies in the 'client/python_env.yaml' file to match your cuda version.
+
+Creating the compute package and seed model
+-------------------------------------------
+
+Install fedn: 
+
+.. code-block::
+
+   pip install fedn
+
+Clone this repository, then locate into this directory:
+
+.. code-block::
+
+   git clone https://github.com/scaleoutsystems/fedn.git
+   cd fedn/examples/FedSimSiam
+
+Create the compute package:
+
+.. code-block::
+
+   fedn package create --path client
+
+This should create a file 'package.tgz' in the project folder.
+
+Next, generate a seed model (the first model in a global model trail):
+
+.. code-block::
+
+   fedn run build --path client
+
+This will create a seed model called 'seed.npz' in the root of the project. This step will take a few minutes, depending on hardware and internet connection (builds a virtualenv).  
+
+Using FEDn Studio
+-----------------
+
+Follow the instructions to register for FEDN Studio and start a project (https://fedn.readthedocs.io/en/stable/studio.html).
+
+In your Studio project:
+
+- Go to the 'Sessions' menu, click on 'New session', and upload the compute package (package.tgz) and seed model (seed.npz).
+- In the 'Clients' menu, click on 'Connect client' and download the client configuration file (client.yaml)
+- Save the client configuration file to the FedSimSiam example directory (fedn/examples/FedSimSiam)
+
+To connect a client, run the following command in your terminal:
+
+.. code-block::
+
+   fedn client start -in client.yaml --secure=True --force-ssl
+
+
+Running the example
+-------------------
+
+After everything is set up, go to 'Sessions' and click on 'New Session'. Click on 'Start run' and the example will execute. You can follow the training progress on 'Events' and 'Models', where you 
+can monitor the training progress. The monitoring is done using a kNN classifier that is fitted on the feature embeddings of the training images that are obtained by
+FedSimSiam's encoder, and evaluated on the feature embeddings of the test images. This process is repeated after each training round.
+
+This is a common method to track FedSimSiam's training progress, as FedSimSiam aims to minimize the distance between the embeddings of similar images.
+A high accuracy implies that the feature embeddings for images within the same class are indeed close to each other in the
+embedding space, i.e., FedSimSiam learned useful feature embeddings.
+
+
+Running FEDn in local development mode:
+---------------------------------------
+
+Follow the steps above to install FEDn, generate 'package.tgz' and 'seed.tgz'.
+
+Start a pseudo-distributed FEDn network using docker-compose:
+.. code-block::
+
+   docker compose \
+    -f ../../docker-compose.yaml \
+    -f docker-compose.override.yaml \
+    up
+
+This starts up local services for MongoDB, Minio, the API Server, one Combiner and two clients. 
+You can verify the deployment using these urls: 
+
+- API Server: http://localhost:8092/get_controller_status
+- Minio: http://localhost:9000
+- Mongo Express: http://localhost:8081
+
+Upload the package and seed model to FEDn controller using the APIClient:
+
+.. code-block::
+
+   from fedn import APIClient
+   client = APIClient(host="localhost", port=8092)
+   client.set_active_package("package.tgz", helper="numpyhelper")
+   client.set_active_model("seed.npz")
+
+
+You can now start a training session with 100 rounds using the API client:
+
+.. code-block::
+
+   client.start_session(rounds=100)
+
+Clean up 
+--------
+
+You can clean up by running
+
+.. code-block::
+
+   docker-compose \
+   -f ../../docker-compose.yaml \
+   -f docker-compose.override.yaml \
+   down -v