{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to set configuration\n",
    "\n",
    "In this notebook, we will provide details about how to set configurations for federated learning experiments.\n",
    "\n",
    "## Load default configuration\n",
    "\n",
    "APPFL empolys [OmegaConf](https://omegaconf.readthedocs.io/) package, a hierarchical configuration system, for FL training configurations.\n",
    "`OmegaConf` package allows users to create a hierarchical configuration in `DictConfig` type from a python `@dataclass`. \n",
    "For example, we can load the APPFL default configuration dataclass using `OmegaConf.structured()` as shown below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from appfl.config import Config\n",
    "from omegaconf import OmegaConf\n",
    "cfg = OmegaConf.structured(Config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The configuration `cfg` is initialized with the default values. Let's check the configuration values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "fed:\n",
      "  type: federated\n",
      "  servername: ServerFedAvg\n",
      "  clientname: ClientOptim\n",
      "  args:\n",
      "    server_learning_rate: 0.01\n",
      "    server_adapt_param: 0.001\n",
      "    server_momentum_param_1: 0.9\n",
      "    server_momentum_param_2: 0.99\n",
      "    optim: SGD\n",
      "    num_local_epochs: 10\n",
      "    optim_args:\n",
      "      lr: 0.001\n",
      "    use_dp: false\n",
      "    epsilon: 1\n",
      "    clip_grad: false\n",
      "    clip_value: 1\n",
      "    clip_norm: 1\n",
      "device: cpu\n",
      "device_server: cpu\n",
      "num_clients: 1\n",
      "num_epochs: 2\n",
      "num_workers: 0\n",
      "batch_training: true\n",
      "train_data_batch_size: 64\n",
      "train_data_shuffle: true\n",
      "validation: true\n",
      "test_data_batch_size: 64\n",
      "test_data_shuffle: false\n",
      "data_sanity: false\n",
      "reproduce: true\n",
      "pca_dir: ''\n",
      "params_start: 0\n",
      "params_end: 49\n",
      "ncomponents: 40\n",
      "use_tensorboard: false\n",
      "load_model: false\n",
      "load_model_dirname: ''\n",
      "load_model_filename: ''\n",
      "save_model: false\n",
      "save_model_dirname: ''\n",
      "save_model_filename: ''\n",
      "checkpoints_interval: 2\n",
      "save_model_state_dict: false\n",
      "send_final_model: false\n",
      "output_dirname: output\n",
      "output_filename: result\n",
      "logginginfo: {}\n",
      "summary_file: ''\n",
      "personalization: false\n",
      "p_layers: []\n",
      "config_name: ''\n",
      "max_message_size: 104857600\n",
      "operator:\n",
      "  id: 1\n",
      "server:\n",
      "  id: 1\n",
      "  host: localhost\n",
      "  port: 50051\n",
      "  use_tls: false\n",
      "  api_key: null\n",
      "client:\n",
      "  id: 1\n",
      "enable_compression: false\n",
      "lossy_compressor: SZ2\n",
      "lossless_compressor: blosc\n",
      "compressor_sz2_path: ../.compressor/SZ/build/sz/libSZ.dylib\n",
      "compressor_sz3_path: ../.compressor/SZ3/build/tools/sz3c/libSZ3c.dylib\n",
      "compressor_szx_path: ../.compressor/SZx-main/build/lib/libSZx.dylib\n",
      "error_bounding_mode: ''\n",
      "error_bound: 0.0\n",
      "flat_model_dtype: np.float32\n",
      "param_cutoff: 1024\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(OmegaConf.to_yaml(cfg))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most variables are self-explanatory. Specifically,\n",
    "\n",
    "- Variable ``fed`` sets the choice of FL algorithm and the algorithm-related parameters, and it is aslo defined as a python `@dataclass`. We provide the definition of those dataclasses at ``appfl.config.fed.*``. In details,\n",
    "  - ``appfl.config.fed.federated`` is a general dataclass for all **synchronous** FL algorithms, where you can specify the server algorithm name at `servername`, client algorithm name at `clientname`, and all related arguments and paramters at `args`.\n",
    "  - ```appfl.config.fed.fedasync``` is a general dataclass for all **asynchronous** FL algorithms, whose `args` contains commonly-used parameters in asynchrnous FL.\n",
    "  - ```appfl.config.fed.iceadmm``` is a dataclass specifically wrote for the ICEADMM privacy-preserving FL algorithm, whose `args` contains all needed parameters for the ICEADMM algorithm.\n",
    "  - ```appfl.config.fed.iiadmm``` is a dataclass specifically wrote for the IIADMM privacy-preserving FL algorithm, whose `args` contains all needed parameters for the IIADMM algorithm.\n",
    "\n",
    "## Initialize configuration with arguments\n",
    "\n",
    "We can also initialize the configuration with other values. For example, the following code is loading the configuration with the algorithm choice of `IIADMM`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "type: iiadmm\n",
      "servername: IIADMMServer\n",
      "clientname: IIADMMClient\n",
      "args:\n",
      "  num_local_epochs: 1\n",
      "  accum_grad: true\n",
      "  coeff_grad: false\n",
      "  optim: SGD\n",
      "  optim_args:\n",
      "    lr: 0.01\n",
      "  init_penalty: 100.0\n",
      "  residual_balancing:\n",
      "    res_on: false\n",
      "    res_on_every_update: false\n",
      "    tau: 1.1\n",
      "    mu: 10\n",
      "  use_dp: false\n",
      "  epsilon: 1\n",
      "  clip_grad: false\n",
      "  clip_value: 1\n",
      "  clip_norm: 1\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from appfl.config import fed\n",
    "cfg = OmegaConf.structured(Config(\n",
    "    fed = fed.iiadmm.IIADMM()\n",
    "))\n",
    "print(OmegaConf.to_yaml(cfg.fed))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change configuration values\n",
    "\n",
    "We can also change the configuration value after initialization. For example, we can change `fed` variable as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "type: fedasync\n",
      "servername: ServerFedAsynchronous\n",
      "clientname: ClientOptim\n",
      "args:\n",
      "  server_learning_rate: 0.01\n",
      "  server_adapt_param: 0.001\n",
      "  server_momentum_param_1: 0.9\n",
      "  server_momentum_param_2: 0.99\n",
      "  optim: SGD\n",
      "  num_local_epochs: 10\n",
      "  optim_args:\n",
      "    lr: 0.001\n",
      "  use_dp: false\n",
      "  epsilon: 1\n",
      "  clip_grad: false\n",
      "  clip_value: 1\n",
      "  clip_norm: 1\n",
      "  K: 3\n",
      "  alpha: 0.9\n",
      "  staleness_func:\n",
      "    name: constant\n",
      "    args:\n",
      "      a: 0.5\n",
      "      b: 4\n",
      "  gradient_based: false\n",
      "\n"
     ]
    }
   ],
   "source": [
    "cfg = OmegaConf.structured(Config)\n",
    "my_fed = OmegaConf.structured(fed.fedasync.FedAsync)\n",
    "cfg.fed = my_fed\n",
    "print(OmegaConf.to_yaml(cfg.fed))"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "201a1c907cd37941086a5fb94e489fb327239b7be498e5e7c17d65ce8de3610b"
  },
  "kernelspec": {
   "display_name": "Python 3.8.5 ('APPFL')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.12"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}