Prepare retreat

.pre-commit-config.yaml

@@ -54,10 +54,10 @@ repos:
         name: isort
         args:
           - --profile=black
-  - repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v2.8.0
-    hooks:
-      - id: setup-cfg-fmt
+#  - repo: https://github.com/asottile/setup-cfg-fmt
+#    rev: v2.8.0
+#    hooks:
+#      - id: setup-cfg-fmt
   - repo: https://github.com/psf/black
     rev: 25.1.0
     hooks:
@@ -106,7 +106,7 @@ repos:
       - id: codespell
         additional_dependencies:
           - tomli
-        exclude: tests/sandbox/|docs/source/Tutorials/interface_plots.ipynb
+        exclude: tests/sandbox/|docs/source/background/interface_plots.ipynb
 # -   repo: https://github.com/mgedmin/check-manifest
 #     rev: "0.49"
 #     hooks:

codecov.yml

@@ -21,3 +21,5 @@ ignore:
   - src/toy_models/*
   - src/dcegm/likelihood.py
   - src/dcegm/wealth_correction.py
+  - src/dcegm/cli.py
+  - src/dcegm/interfaces/interface.py

docs/source/Tutorials/interface_plots.ipynb → docs/source/background/interface_plots.ipynb

@@ -264,7 +264,7 @@
     "    \"period\": 37,  # Periods start at 0, the last period number T=44 has index 43 so period T-5 has index 38\n",
     "    \"lagged_choice\": 0,  # choice in the previous period d_{t-1}, zero meaning working\n",
     "    \"choice\": 0,  # choice in the current period d_t, zero meaning working\n",
-    "    \"dummy_exog\": 0,  # dummy exogenous state variable can be ignored for now\n",
+    "    \"dummy_stochastic\": 0,  # dummy exogenous state variable can be ignored for now\n",
     "}\n",
     "\n",
     "# get the index of the state choice pair in the endogenous grid\n",
@@ -346,7 +346,7 @@
     "    state_choice_dict = {\n",
     "        \"period\": 37,\n",
     "        \"lagged_choice\": 0,\n",
-    "        \"dummy_exog\": 0,\n",
+    "        \"dummy_stochastic\": 0,\n",
     "        \"choice\": 0,\n",
     "    }\n",
     "    value, policy, endog_grid = solve_func(params)\n",
@@ -420,7 +420,7 @@
     "    state_choice_dict = {\n",
     "        \"period\": 37,\n",
     "        \"lagged_choice\": 0,\n",
-    "        \"dummy_exog\": 0,\n",
+    "        \"dummy_stochastic\": 0,\n",
     "        \"choice\": 0,\n",
     "    }\n",
     "    value, policy, endog_grid = solve_func(params)\n",
@@ -585,7 +585,7 @@
     "                state_choice_dict = {\n",
     "                    \"period\": test_period,\n",
     "                    \"lagged_choice\": 0,\n",
-    "                    \"dummy_exog\": 0,\n",
+    "                    \"dummy_stochastic\": 0,\n",
     "                    \"choice\": 0,\n",
     "                }\n",
     "                value, policy, endog_grid = solve_func(params)\n",

docs/source/background/limitations.rst

@@ -0,0 +1,10 @@
+.. _limitations:
+
+Limitations
+===========
+
+`dc-egm` is a versatile Python package capable of solving and simulating a large class of economic models flexibly and efficiently..
+
+However, there are limitations to what kind of features can be implemented and how complex models can become to be feasible to solve.
+
+Below we discuss what kind of models `dc-egm` is designed for and importantly what limitations to be aware of when implementing a model.

docs/source/background/literature.rst

@@ -0,0 +1,6 @@
+.. _literature:
+
+Literature
+==========
+
+Below you find related literature to provide a background of the `dc-egm` algorithm and the related class of economic models.

docs/source/How-To/specify_exogenous_processes.md → docs/source/background/specify_exogenous_processes.md

@@ -34,7 +34,7 @@ Each exogenous process should be defined in the `state_space` section of the mod
 ```python
 options = {
     "state_space": {
-        "exogenous_processes": {
+        "stochastic_states": {
             "health_mother": {
                 "transition": prob_exog_health_mother,
                 "states": [0, 1, 2],
@@ -53,9 +53,9 @@ options = {
 To ensure correctness, the validation function can be used as implemented in the ```dcegm``` module:
 
 ```python
-from dcegm.interface import validate_exogenous_processes
+from dcegm.interfaces.interface import validate_stochastic_states
 
-validate_exogenous_processes(model, params)
+validate_stochastic_states(model, params)
 ```
 
 This function checks for compliance with probability constraints and verifies that transition matrices align with the model's state space. Possible errors and their respective messages include:

docs/source/background/timing_benchmarks.ipynb

@@ -0,0 +1,27 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "2f7d8c63",
+   "metadata": {},
+   "source": [
+    "## Solution Speed Benchmarks\n",
+    "\n",
+    "Below you find benchmakrs to compare the solution speed of the `dc-egm` for models with differing degrees of complexity."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2e45e97f",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/source/development/team.rst

@@ -0,0 +1,23 @@
+.. _team:
+
+
+Team
+=======
+
+
++---------------------------------------------------------------+-------------------------------------------------------------------+
++ .. figure:: ../_static/images/max.jpeg                        + .. figure:: ../_static/images/sebastian.jpeg                       +
++     :width: 120px                                             +     :width: 120px                                                 +
++                                                               +                                                                   +
++     `Max Blesch <https://github.com/MaxBlesch>`_              +     `Sebastian Gsell <https://github.com/segsell>`_               +
++---------------------------------------------------------------+-------------------------------------------------------------------+
++ .. figure:: ../_static/images/bruno.jpeg                      + .. figure:: ../_static/images/annica.jpeg                          +
++     :width: 120px                                             +     :width: 120px                                                 +
++                                                               +                                                                   +
++     `Bruno Veltri <https://github.com/BVeltri>`_              +     `Annica Gehlen <https://github.com/amageh>`_                  +
++---------------------------------------------------------------+-------------------------------------------------------------------+
++ .. figure:: ../_static/images/gregor.png                      + .. figure:: ../_static/images/Frederik.jpeg                        +
++     :width: 120px                                             +     :width: 120px                                                 +
++                                                               +                                                                   +
++     `Gregor Schueler <https://github.com/gregor-schueler>`_   +     `Frederik Emil Larsen <https://github.com/LarsenFred>`_       +
++---------------------------------------------------------------+-------------------------------------------------------------------+

docs/source/guides/practitioner_guides/model_config.ipynb

@@ -0,0 +1,143 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c46eeec3",
+   "metadata": {},
+   "source": [
+    "# Model Configuration Guide\n",
+    "\n",
+    "`dc-egm` requires a number of inputs to correctly specify a dynamic model. These configurations are saved in  the dictionary `model_config`. \n",
+    "\n",
+    "There are a number of required inputs without which `dc-egm` throws an error message. Depending on the desired model features, further configurations are required."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3d9e0366",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ba5fa998",
+   "metadata": {},
+   "source": [
+    "### Required configurations\n",
+    "\n",
+    "1. Number of periods in the model"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d440600f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_config = {}\n",
+    "model_config[\"n_periods\"] = 5"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b0e28be3",
+   "metadata": {},
+   "source": [
+    "2. Number of (discrete) choices"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "03e2e0bf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Pass an integer\n",
+    "model_config[\"choices\"] = 3\n",
+    "\n",
+    "# or a list\n",
+    "model_config[\"choices\"] = [0, 1, 2]\n",
+    "\n",
+    "# or a numpy array\n",
+    "model_config[\"choices\"] = np.array([0, 1, 2])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ec75f15f",
+   "metadata": {},
+   "source": [
+    "3. Asset grid"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "75081f3f",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ed83f1c6",
+   "metadata": {},
+   "source": [
+    "4. Quadrature points"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6f9fe97a",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fad03a16",
+   "metadata": {},
+   "source": [
+    "### Further configurations"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b8a90e05",
+   "metadata": {},
+   "source": [
+    "1. Endogenous discrete states"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f4a97c99",
+   "metadata": {},
+   "source": [
+    "2. Stochastic discrete states"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18363280",
+   "metadata": {},
+   "source": [
+    "3. Continuous states"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/source/guides/practitioner_guides/parameters.ipynb

@@ -0,0 +1,80 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "576ae8a0",
+   "metadata": {},
+   "source": [
+    "# Parameterization Guide"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8090e40f",
+   "metadata": {},
+   "source": [
+    "`dc-egm` used two different dictionaries to store model parameters: `params` which are estimated *within* the model and `model_specs` which are calibrated or estimated *outside* the model. \n",
+    "\n",
+    "Both objects should be defined as dictionaries which map string labels to numeric parameter values.\n",
+    "\n",
+    "\n",
+    "### `params`\n",
+    "\n",
+    "`params` stores *estimable* model parameters, i.e. parameters that can be retrieved using the structural model and empirical data using an statistical estimation procedure (like maximum likelihood estimation or minimum-distance estimators).\n",
+    "\n",
+    "A common example for a parameter of interest that would be subject to estimation is the return to experience in a labor supply model.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8e54e898",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a3dd26fb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example of params\n",
+    "params = {}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5b09c616",
+   "metadata": {},
+   "source": [
+    "### `model_specs`\n",
+    "\n",
+    "`model_specs` denotes parameters or *model specifications* which are not estimated inside the model but should be passed on to `dc-egm` to be used in utility functions, the budget constraint, or other state space functions. \n",
+    "\n",
+    "These are parameters which can be obtained using reduced-form estimation methods or calibrated using prior knowledge about the policy context.\n",
+    "\n",
+    "An example for a parameter that should be stored in `model_specs` would be the market interest rate or policy parameters like tax rates.  \n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3a932eda",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example of model specs\n",
+    "\n",
+    "model_specs = {}"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}