Merge pull request #18 from xenophonlabs/dev

Update app

.gitattributes

@@ -0,0 +1 @@
+results/** filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,9 +1,10 @@
 # Custom
 *.prof
 logs/*
-results/*
+# results/*
 figs/results/*
 *dev.ipynb
+.DS_Store
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.11
+
+WORKDIR /code
+
+# Set your GitHub repo URL here
+ARG GIT_REPO_URL=https://github.com/xenophonlabs/crvUSDrisk.git
+ARG GIT_BRANCH=dev  # Adjust the branch name as necessary
+
+# Install system dependencies required for gmpy2 compilation
+RUN apt-get update && apt-get install -y \
+    libgmp-dev \
+    libmpfr-dev \
+    libmpc-dev \
+    git \
+    git-lfs \
+    && rm -rf /var/lib/apt/lists/* 
+
+RUN git lfs install
+RUN git clone --branch $GIT_BRANCH $GIT_REPO_URL . && git lfs pull
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --upgrade pip
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+ENV PYTHONPATH "${PYTHONPATH}:/code"
+
+CMD ["python", "./app/main.py"]

README.md

@@ -6,28 +6,25 @@ crvusd Risk Modeling
 [![CI](https://github.com/xenophonlabs/crvUSDrisk/actions/workflows/CI.yml/badge.svg)](https://github.com/xenophonlabs/crvUSDrisk/actions/workflows/CI.yml/badge.svg)
 ![Plotly](https://img.shields.io/badge/Plotly-%233F4F75.svg?style=flat&logo=plotly&logoColor=white)
 
-**Under construction 👷🏽‍♂️**
+### Overview
 
-crvUSD Risk is a tool for Curve’s researchers and developers to test the resiliency of the crvUSD ecosystem under a variety of market conditions. 
+crvUSDRisk is a tool for Curve’s researchers and developers to test the resiliency of the crvUSD ecosystem under a variety of market conditions. 
 
-### Quick Start
+The codebase is organized into four components:
 
-To view the risk dashboard, follow the steps in [Setup](#setup). Then, download some sample results from [this Google Drive folder](https://drive.google.com/drive/folders/13f6Z8FHI-NTGIbm67hdHpm2Q_IIq9sIs?usp=sharing), and run the app:
+1. `src` contains all the logic for the underlying risk model.
+2. `app` contains all the logic for deploying our Plotly Dashboard for viewing results. Find the dashboard [here](https://crvusdrisk-dashboard.up.railway.app/).
+3. `scripts` contains all the logic for running the model.
+4. `notebooks` contains some demos for different aspects of the model.
 
-```python
-python3 -m app.app
-```
-
-You may also run your own simulations as instructed in [Usage](#usage).
+Our analysis of initial model results can be found in this report: https://xenophonlabs.com/papers/A_Quantitative_Risk_Model_for_crvUSD.pdf.
 
 ### Table of Contents
 
 1. [Setup](#setup)
-2. [Usage](#usage)
+2. [Running the Model](#usage)
 3. [Dashboard](#dashboard)
-4. [Conceptual Overview](#conceptual-overview)
-
-*More detailed documentation coming soon.*
+4. [Analysis](#analysis)
 
 # Setup
 
@@ -42,91 +39,40 @@ python3 -m pip install -r requirements.txt
 
 Only Python3.11 is guaranteed support. Notice that the requirements point to a fork of `crvusdsim`. *We are working on replacing this dependency with stable release.*
 
-# Usage
-
-## Viewing Results
-
-The recommended way to analyze simulation results is via our Plotly Dash app. To run the app:
-
-```bash
-python3 -m app.app
-```
-
-Simply select to load a results file (`.pkl`), or run your own simulation.
-
-### Viewing Saved Results
+# Running the Model
 
-We provide sample simulation results for the `baseline` scenario in [this](https://drive.google.com/drive/folders/13f6Z8FHI-NTGIbm67hdHpm2Q_IIq9sIs?usp=sharing) google drive. Please download it into the root directory and ensure you are using local results in `./app/app.py`.
+The model is run via the python and bash scripts in `scripts`. 
 
-## Running Simulations
+### Single Model Run
 
-To run simulations, please create `logs` and `results` folders in your root directory.
+We can perform a single model run with the command:
 
-### From the Dashboard
-
-Select a `scenario`, `market`, and number of iterations (model runs) for you scenario and click the simulate button. Your terminal will begin to print the logs for the simulation. 
+```
+python3 -m scripts.sim <scenario> <num_iter> -mp -a
+```
 
-*Simulations may take a long time to finalize; by default, multiprocessing will be applied using all your machine's processors. It is much faster to run simulations directly from the command line.*.
+where `scenario` is the name of the scenario you want to run (refer to `/src/configs/scenarios.py`) and `num_iter` is the number of iterations you want to run (e.g. 1000). The optional flags `-mp` and `-a` will run the scenario using multiprocessing (by default will max out all of your CPUs) and will dumb a profile of the code respectively.
 
-### From the Command Line
+### Parameter Sweeps
 
-Alternatively, you may run a simulation via the `scripts/sim.py` script as follows:
+When we run our scenarios under different parameter configurations for the crvUSD protocol (such as varying fees or Chainlink limits) we call this an `experiment`. We have configured a few experiments under `scripts/experiments` which can be run with:
 
-```bash
-python3 -m scripts.sim baseline 100 -mp &> logs/sim.log
+```
+nohup ./scripts/experiments/run_experiments.sh &
 ```
 
-Make sure to create the `logs` directory to view simulation logs/warnings, or remove the `&> logs/sim.log` redirection.
+You'll want to run it with `nohup` since these experiments can take a very long time, especially without many CPUs.
 
-### In a Notebook
+### Updating Model Configs
 
-Follow the instructions in `notebooks/demo_monte_carlo.ipynb` to run simulations in a Jupyter notebook or `notebooks/demo_sim.ipynb` to run a single simulation.
+The prices, liquidities, and other necessary scenario/parameter configurations are all contained in `src/configs`. Many of the config files are generated by running the corresponding scripts in `scripts`.
 
 # Dashboard
 
-The Risk Dashboard allows the user to analyze the results of a given model run. Ultimately, the dashboard will allow users to compare the results from model runs with different parameter configurations (e.g. Debt Ceilings) to identify parameter improvements for the crvUSD system.
-
-The results for 1000 runs of the `Baseline Macro` scenario (in the Google Drive) are shown below.
-
-### Summary Metrics
-
-![Summary Tab](./figs/samples/summary.png)
-*Summary Tab*
-
-### Per-Run Metrics
-![Per Run Metrics](./figs/samples/per_run_metrics.png)
-*Per Run Metrics Tab*
-
-### Per-Run Prices
-![Per Run Prices](./figs/samples/per_run_prices.png)
-*Per Run Prices*
-
-### Modeled External Liquidity
-![Liquidity](./figs/samples/liquidity.png)
-*Liquidity*
-
-# Conceptual Overview
-
-**Research paper:** [link](https://xenophonlabs.com/papers/_INTERNAL__An_ABS_Engine_for_crvUSD.pdf)
-
-One of the primary purposes of crvUSD Risk simulations is to analyze the impact of available crvUSD liquidity on crvUSD liquidations. We explicitly simulate arbitrageurs and liquidators trading against the relevant LLAMMAs and Curve pools using the [curvesim](https://github.com/curveresearch/curvesim/tree/main) and [crvusdsim](https://github.com/0xreviews/crvusdsim) packages. This allows us to understand the impact of liquidity and liquidations themselves on the health of the crvUSD system.
-
-For a quick introduction to the key agents in our agent-based model and the overall simulation architecture, please refer to the `./notebooks/demo_*` notebooks!
-
-![Liquidation Model](./figs/samples/oracle_risk.png)
-*Liquidation Model*
-
-## Inputs
-
-When running a simulation, we fetch the most updated data for the relevant crvUSD modules, including LLAMMAs, Controllers, StableSwap pools, etc.. We generate prices using empirically-trained Geometric Brownian Motion processes (for collateral) and Ornstein-Uhlenbeck processes (for stablecoins). We also simulate the "external" liquidity for all relevant tokens (please refer to [this repo](https://github.com/xenophonlabs/oneinch-quotes) for more detail on our liquidity model).
-
-## Stress Testing
-
-Inputs are generated according to "Stress Scenario" configurations in `./src/configs/scenarios`. Currently, only the `baseline` scenario is supported.
+Results for the model runs detailed in our report can be analyzed in this Plotly Dashapp: [crvusdrisk.up.railway.app](crvusdrisk.up.railway.app). The dashboard is the best way to easily analyze individual model runs.
 
-## Agent Based Modeling
+# Analysis
 
-Below is the overview for the ABM architecture.
+Our analysis of initial model results can be found in this report: https://xenophonlabs.com/papers/A_Quantitative_Risk_Model_for_crvUSD.pdf.
 
-![Architecture](/figs/samples/architecture.png)
-*ABM Architecture*
+We used the `analysis.ipynb` notebook in `notebooks` to compare results across many scenarios.