diff --git a/README.md b/README.md
deleted file mode 100644
index 0cfc26b739..0000000000
--- a/README.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# DYNAMOD - Dynamic Modelling of the German Tax Transfer System #
-
-
-
-**For details on the modelling of the tax-benefit system, you may check out `doc_files` in the IZAΨMOD repository, in particular `doku.pdf` and the graphs in the `flowcharts` directory.**
-
-## Technical Remarks
-- In order to clone including submodules, please clone via
-
- ```bash
- $ git clone --recurse-submodules https://git.econ.tools/dynamod/dynamod.git
- ```
- If you cloned the repo without the recursive flag and find your submodules empty, pull the content with
- ```bash
- $ cd custompygraph
- $ git submodule update --init
- $ git checkout HEAD
- ```
-- The data for the test cases are prepared in Excel as we make use of formulas. When opening these files in Libreoffice Calc, boolean values (e.g. for `child` oder `east`) might be displayed as `0/1` instead of `TRUE/FALSE`.
-Changing the tests with calc might hence lead to failure, as the function requires the `pandas` boolean type. **Remedy:** Change the format in Calc to *booelan* by selecting the respective cells and hitting `Ctrl+1`.
-- The data preparation is outsourced into separate repositories. In order to work smoothly, place these repos into the same root folder as this repo.
-Alternatively, you may change the respective path (`SOEP_PATH`, `SIAB_PATH`, etc.) in `wscript`.
-
-## Sources for Cross-validation.
-
-- The [OECD TaxBen model](http://www.oecd.org/social/benefits-and-wages/) is publicly available. You find a concise description of policies. One can start own model runs.
-
-## Assumptions in SOEP data preparation
-- Persons are uniquely identified via `syear` and `pid`.
-- A household member is defined as a child if (under 18) or (under 25 and in education). Unless it's the household head or his/her partner
-- Earnings:
- - Monthly earnings are summed up from earnings from all jobs. This is a simplification as the 2nd job might be tax-free if it's paid below 450€.
- - To this, other wage components (13th salary, bonus payments) are added. Since this information stems from the previous year, it is divided by the number of months in work.
- - If "stellung im Beruf" is self-employed, these earnings count as self-employed income `m_self`. Otherwise, it's labor income `m_wage`.
-- Non-workers are assigned a potential hourly wage via Heckman Imputation. (function `heckman()` in `2_prepare_data.py`)
-- `m_transfers` encompasses all private transfers (alimony mainly) and public transfers which we do not simulate (e.g. Parental Benefit, BaföG)
-- Renting costs `hgrent` and heating costs `hgheat` exhibit many missings. Missing values are imputed in order to have some idea on benefit claim. It's better to be somewhat off than to assume no renting costs.
-
-## Implicit Assumptions in Tax-Benefit calculations ##
-
-- Calculation of taxable income (`zve()`):
- - In lack of more detailed information, we always deduct the lumpsum amount `werbung` (currently € 1000) which is the lower bound
- - The same holds for Sonderausgaben (`sonder` = € 36)
-- Income Tax Calculation:
- - married couples are assumed to file jointly. This is not a brave assumption; they are always better off that way.
-- Housing Benefit (Wohngeld):
- - There is an upper threshold `tg["wgmax?p_m"], (? = [1,2,4,5,plus5])` up to which rents are considered in the wohngeld formula. These values differ by *Mietstufe* (I: Eifel village , V: Bonn, VI: Köln).
-We don't know the municipality and hence the Mietstufe. We assume instead Mietstufe III for *everyone*, which is supposed to capture a medium level. This leads to undercoverage of housing benefit in large, expensive cities.
-- Unemployment Benefit (ALG 2):
- - Housing costs are paid if *appropriate*.
- - We cap rents to €10 per square meter. In 2017, actual acknowledged cost of ALG2 recipients were in average between €8 and €9.
- - There is a *Faustregel* on the maximum size of the flat:
- - For Renters: 45 sqm plus 15 sqm for each additional person
- - For Owners: 80 sqm plus 20 sqm for each additional person after third
- - *Kosten der Unterkunft* (`alg2_kdu`) are hence calculated by maximum 10€ per sqm, multiplied by minimum of actual flat size and Faustregel.
- - For the Asset Test, we impute assets via capital income and some average interest rate (tb['r_assets']). This should be replaced by either imputed wealth from EVS, or wealth observed in SOEP wave 2017.
-
-## Necessary input for tax_transfer() elements ##
-
-### soc_ins_contrib() ###
-- `pid`: Personal Identifier
-- `m_wage`: Monthly earnings from Employment
-- `m_self`: Monthly Self-Employment Income
-- `m_pensions`: Monthly old-age pensions
-- `east` (boolean): East Germany
-- `age`
-- `selfemployed` (boolean): Self-Employment Status
-- `haskids` (boolean): Person has kids (in and outside the household!)
-- `pkv` (boolean): Person has private health insurance
-
-### ui() ###
-- `pid`: Personal Identifier
-- `m_wage_l1`: Monthly Earnings from previous year
-- `east` (boolean): East Germany
-- `child` (boolean)
-- `months_ue`: Months in unemployment, current year
-- `months_ue_l`: Month in unemployment, previous year
-- `months_ue_l2`: Month in unemployment, two years ago
-- `m_pensions`: Monthly old-age pensions
-- `w_hours`: Weekly working hours
-- `child_num_tu`: Number of children in Tax Unit
-- `age`
-
-### zve() ###
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `m_wage`: Monthly Earnings
-- `m_self`: Monthly Self-Employment Income
-- `m_kapinc`: Monthly capital income
-- `m_vermiet`: Monthly rental income
-- `renteneintritt`: Year of entering old-age retirement. **can easily be calculated within the function**
-- `m_pensions`: Monthly old-age pensions
-- `east` (booelan): East Germany
-- `zveranl` (boolean): Adults within a married couple who file jointly
-- `child` (boolean)
-- `handcap_degree` [0,100]: Degree of disability
-- `rvbeit`: Monthly old-age pension contributions, output from `soc_ins_contrib()`
-- `avbeit`: Monthly unemployment insurance contributions, output from `soc_ins_contrib()`
-- `gkvbeit`: Monthly statutory health insurance contributions, output from `soc_ins_contrib()`
-- `pvbeit`: Monthly long-term care insurance contributions, output from `soc_ins_contrib()`
-- `alleinerz` (boolean): Single Parent
-- `age`
-- `child_num_tu`: Number of children in tax unit
-
-### tax_sched() ###
-- `tu_id`: Tax Unit Identifier
-- `zve_x_y`: taxable income... (output from `zve()`)
- - x = ["", abg]: without and with capital income included
- - y = [nokfb, kfb]: without and with child tax allowance
-- `gross_e5`: **annual** capital income (5th type of taxable incomes), output from `zve()`
-- `gross_e5_tu`: annual capital income, sum within the tax unit, output from `zve()`
-- `zveranl` (boolean): Adults within a married couple who file jointly
-
-### kindergeld() ###
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifer
-- `age`
-- `w_hours`: Weekly working hours
-- `ineducation` (boolean)
-- `m_wage`: Monthly Earnings
-
-### favorability_check() ###
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `zveranl` (boolean): Adults within a married couple who file jointly
-- `child` (boolean)
-- `tax_x_y`: income tax for different tax bases (output from `tax_sched()`):
- - x = ["", abg]: without and with capital income included
- - y = [nokfb, kfb]: without and with child tax allowance
-- `abgst_tu`: Capital income tax (Abgeltungssteuer), sum within tu_id.
-- `kindergeld_basis`: Output from `kindergeld()`
-- `kindergeld_basis`: Output from `kindergeld()`, **can be calculated within function**
-
-### soli() ###
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `zveranl` (boolean): Adults within a married couple who file jointly
-- `child` (boolean)
-- `incometax_tu`: optimal income tax, output from `favorability_check()`.
-- `tax_kfb_tu`: Income tax with child tax allowance, output from `tax_sched()`
-- `tax_kfb_abg_tu`: As above, but with capital income included, needed before 2009. Output from `tax_sched()`
-- `abgst_tu`: Capital income tax, output from `tax_sched()`
-
-### uhv() ###
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `zveranl` (boolean): Adults within a married couple who file jointly
-- `age`
-- `alleinerz` (boolean): Single Parent
-- `m_wage, m_transfers, m_self, m_vermiet, m_kapinc, m_pensions, m_alg1`: Income from various sources
-
-### wg() ###
-- `hid`: Household Identifier
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `head_tu` (boolean): Dummy for Head of Tax Unit
-- `child` (boolean)
-- `miete`: monthly rent without heating
-- `heizkost`: monthly heating costs
-- `alleinerz` (boolean): Single Parent
-- `child11_num_tu`: number of children below 11 in tax unit ** can be calculated within function **
-- `cnstyr` [1,2,3]: Indicator for construction year of house; relevant before 2009. Set it to `2` if in doubt.
-- `m_wage`: Monthly Earnings
-- `m_pensions`: Monthly old-age pensions
-- `ertragsanteil`: Taxable Share of pensions, output from `zve()`.
-- `uhv`: Monthly alimony payments, output from `uhv()`.
-- `m_alg1`: Monthly unemployment benefits, output from `ui()`
-- `m_transfers`: Monthly private and public transfers that are not simulated.
-- `gross_e1, gross_e4, gross_e5, gross_e6`: Annual income from self-employment, employment (incl. werbungskosten), capital and rental
-- `incometax`: monthyl income Tax payments, output from `soli()`.
-- `rvbeit`, `gkvbeit`: monthly contributions for old-age pension and health insurance respectively, output from `soc_ins_contrib()`
-- `handcap_degree`: Degree of disability
-- `divdy`: annual capital income. ** only needed for asset test **
-
-### alg2() ###
-- `hid`: Household Identifier
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `head_tu` (boolean): Dummy for Head of Tax Unit
-- `child` (boolean)
-- `age`
-- `byear`: Birth Year ** can be calculated within function **
-- `miete`: monthly rent without heating
-- `heizkost`: monthly heating costs
-- `wohnfl`: Size of flat/house in square meters.
-- `eigentum` (boolean): Dummy on living in own property.
-- `m_wage`, `m_pensions`, `m_kapinc`,` m_transfers`, `m_self`, `m_vermiet`: Income from various sources
-- `m_alg1`: Unemployment benefit, output from `ui()`
-- `incometax`: monthyl income Tax payments, output from `soli()`.
-- `svbeit`: sum of monthly contributions, output from `soc_ins_contrib()`
-- `soli`: monthly Solidarity Surcharge payments, output from `soli()`
-- `kindergeld_hh`: monthly child benefit for the household, outputfrom `favorability_check()`
-- `uhv`: monthly child alimony, output from `uhv()`
-- `divdy`: annual capital income. ** only needed for asset test **
-
-
-### kiz() ###
-- `hid`: Household Identifier
-- `tu_id`: Tax Unit Identifier
-- `pid`: Personal Identifier
-- `head` (boolean): Dummy for household head
-- `hhtyp`: 1: Single, 2: Single Parent, 3: Couple without kids, 4: Couple with kids
-- `child` (boolean)
-- `pensioner`(boolean)
-- `age`
-- `miete`: monthly rent without heating
-- `heizkost`: monthly heating costs
-- `alleinerz`: Dummy for single parent
-- `mehrbed`: Additional need, output from `alg2()`. ** can be calculated within the function, copy code from `alg2()` **
-- `alg2_grossek_hh`: monthly gross hh income for ALG2, output from `alg2()`
-- `ar_alg2_ek_hh`: monthly net hh income for ALG2, output from `alg2()`
-- `wohngeld_basis_hh`: housing benefit claim, output from `wg()`
-- `regelbedarf`: household basic need, output from `alg2()`
-- `ar_base_alg2_ek`: `ar_alg2_ek_hh` + `kindergeld_hh` + `uhv_hh`, output from `alg2()`
-- `kindergeld_hh`: monthly child benefit for the household, outputfrom `favorability_check()`
-- `uhv`: monthly child alimony, output from `uhv()`
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000..9996c1f464
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,55 @@
+.. image:: https://dev.azure.com/iza-institute-of-labor-economics/gettsim/_apis/build/status/iza-institute-of-labor-economics.gettsim?branchName=master
+ :target: https://dev.azure.com/iza-institute-of-labor-economics/gettsim/_build/latest?definitionId=1&branchName=master
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+ :target: https://github.com/ambv/black
+
+.. raw:: html
+
+
+
+
+
+ 
+
+
+
+
+
+GETTSIM aims at providing a depiction of the German Taxes and Transfers System that is usable across a wide range of research applications, ranging from highly complex dynamic programming models to extremely detailed microsimulation studies.
+
+GETTSIM is implemented in Python and Numba, thereby achieving both flexibility and speed. All features are extensively tested.
+
+The current version is usable, but probably only by the initiated. Please get in touch (via an issue or emailing `Hans-Martin von Gaudecker `_ if you want to use it already, else keep an eye out for what there is to come!
+
+
+Initiated by
+============
+
+.. raw:: html
+
+
+
+ 
+
+
+
+
+ 
+
+
+
+
+ 
+
+
+
+
+ 
+
+
+
+
+ 
+
+
diff --git a/pics/diw_logo.jpg b/pics/diw_logo.jpg
new file mode 100644
index 0000000000..430676fbcd
Binary files /dev/null and b/pics/diw_logo.jpg differ
diff --git a/pics/gettsim_logo.png b/pics/gettsim_logo.png
new file mode 100644
index 0000000000..f412e8c8c4
Binary files /dev/null and b/pics/gettsim_logo.png differ
diff --git a/pics/gettsim_logo_text.png b/pics/gettsim_logo_text.png
new file mode 100644
index 0000000000..8b40ae1b1b
Binary files /dev/null and b/pics/gettsim_logo_text.png differ
diff --git a/pics/iza_logo.jpg b/pics/iza_logo.jpg
new file mode 100644
index 0000000000..3142c9d060
Binary files /dev/null and b/pics/iza_logo.jpg differ
diff --git a/pics/uni_bonn_logo.png b/pics/uni_bonn_logo.png
new file mode 100644
index 0000000000..ae87f859e4
Binary files /dev/null and b/pics/uni_bonn_logo.png differ
diff --git a/pics/zew_logo.png b/pics/zew_logo.png
new file mode 100644
index 0000000000..1946fbffd9
Binary files /dev/null and b/pics/zew_logo.png differ