docs/install.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation and Quickstart\n",
    "\n",
    "## Prerequisites\n",
    "\n",
    "It is strongly recommended that you install summer2 in a managed environment rather than your system Python installation.\n",
    "\n",
    "You can install a minimal version of the Anaconda package and environment manager (\"Miniconda\") [here](https://docs.conda.io/en/latest/miniconda.html).\n",
    "\n",
    "In any case, you will need to have Python 3.8+ and Pip (the Python package manager) available.\n",
    "\n",
    "If you are using Miniconda, then you will need to create an \"environment\" where you can install Summer and other packages you need for your project. You can create a new environment as follows:\n",
    "\n",
    "```bash\n",
    "# Create a new Anaconda environment.\n",
    "conda create -n myprojectname python=3.8\n",
    "# Make the new Anaconda environment active in your shell session.\n",
    "conda activate myprojectname\n",
    "```\n",
    "\n",
    "## Installation\n",
    "\n",
    "You can install summer2 from PyPI using the Pip package manager\n",
    "\n",
    "```bash\n",
    "pip install summerepi2\n",
    "```\n",
    "\n",
    "Important note for Windows users:\n",
    "\n",
    "summer2 relies on the [Jax](https://jax.readthedocs.io) framework for fast retargetable computing. \n",
    "This is automatically installed by pip under Linux, OSX, and WSL environments. \n",
    "If you are using Windows, you can either install via WSL, or run the following command after pip installing\n",
    "\n",
    "```bash\n",
    "pip install jax[cpu]==0.3.24 -f https://whls.blob.core.windows.net/unstable/index.html\n",
    "```\n",
    "\n",
    "\n",
    "\n",
    "For other install methods, see https://pygraphviz.github.io/documentation/stable/install.html\n",
    "\n",
    "Then you can import the library as `summer2` and get started building compartmental disease models. You can find a [list of examples](./examples/index.rst) and [detailed API documentation](./api/index.rst) on this site.\n",
    "\n",
    "Note the above method installs the latest 'release' version of summer, but that this documentation is based on the current Github master version of summer, which may contain new features or changes to the API. \n",
    "To install summer directly from Github, use the following command instead\n",
    "\n",
    "```bash\n",
    "pip install git+https://github.com/monash-emu/summer2.git\n",
    "```\n",
    "\n",
    "## Optional (but recommended) extras\n",
    "\n",
    "Summer has advanced interactive plotting tools built in - but they are greatly improved with the addition of the pygraphviz library.\n",
    "\n",
    "If you are using conda, the simplest method of installation is as follows:\n",
    "\n",
    "```bash\n",
    "conda install --channel conda-forge pygraphviz\n",
    "```\n",
    "\n",
    "## Quick Example Model\n",
    "\n",
    "This is a short example on how summer can be used. See the [list of examples](./examples/index.html) for more."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from summer2 import CompartmentalModel\n",
    "from summer2.functions.time import get_piecewise_scalar_function\n",
    "\n",
    "import pandas as pd\n",
    "pd.options.plotting.backend = \"plotly\"\n",
    "\n",
    "# Create a model.\n",
    "model = CompartmentalModel(\n",
    "    times=[1990, 2025],\n",
    "    compartments=[\"S\", \"I\", \"R\"],\n",
    "    infectious_compartments=[\"I\"],\n",
    "    timestep=0.1,\n",
    ")\n",
    "\n",
    "# Add people to the model.\n",
    "model.set_initial_population(distribution={\"S\": 1000, \"I\": 10})\n",
    "\n",
    "# Add intercompartmental flows.\n",
    "model.add_infection_frequency_flow(name=\"infection\", contact_rate=1.2, source=\"S\", dest=\"I\")\n",
    "model.add_transition_flow(name=\"recovery\", fractional_rate=1/6, source=\"I\", dest=\"R\")\n",
    "model.add_death_flow(name=\"infection_death\", death_rate=0.5, source=\"I\")\n",
    "\n",
    "# Spice up the model by importing 500 infected people over the course of 2005\n",
    "get_infected_imports = get_piecewise_scalar_function([2005,2006], [0.0,500.0,0.0])\n",
    "\n",
    "model.add_importation_flow('infected_imports', get_infected_imports, 'I', split_imports=True)\n",
    "\n",
    "# Run the model\n",
    "model.run()\n",
    "\n",
    "# Plot the model results.\n",
    "model.get_outputs_df().plot()\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "jaxtest",
   "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.9.13"
  },
  "vscode": {
   "interpreter": {
    "hash": "79d70c6600ff0f236e7435c5ae4904b6925bd23ac9f566aeb17edb414d890ad2"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}