{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation\n",
    "\n",
    "This section will guide you through the process of installing the CIMantic Graphs library, either from from PyPI or by cloning the git repository and building the wheel using Poetry."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prerequisites\n",
    "\n",
    "Before you start, make sure you have a python environment with:\n",
    "\n",
    "* [Python 3.10+](https://www.python.org/downloads/)\n",
    "\n",
    "Use of CIM-Graph with external databases, such as Neo4J and GraphDB requires installation of those databases using the recommended instructions from the database provider. A sample Docker file is provided in the [CIM-Graph github](https://github.com/PNNL-CIM-Tools/CIM-Graph/blob/main/docker-compose.yml) to pull the databases with the correct configuration. Use of a database is not strictly required by CIM-Graph."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installating from PyPi\n",
    "\n",
    "To install the library directly from PyPI, you can use pip. Follow these steps:\n",
    "\n",
    "1. Open your terminal.\n",
    "\n",
    "2. Run the following command to install the library:\n",
    "\n",
    "```sh\n",
    "pip install cim-graph\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing from Source"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing Poetry\n",
    "\n",
    "Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.\n",
    "\n",
    "All tools in the PNNL-CIM-Tools family use Poetry for distribution and packaging.\n",
    "\n",
    "To install Poetry, do NOT use the pypi installer. Instead, use the official cli installer:\n",
    "\n",
    "* In Linux, MacOS, WSL2:\n",
    "\n",
    "```sh\n",
    "curl -sSL https://install.python-poetry.org | python3 -\n",
    "```\n",
    "\n",
    "* In Windows Powershell:\n",
    "\n",
    "```bash\n",
    "(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -\n",
    "```\n",
    "\n",
    "After running the cli installer, add Poetry to your default path using\n",
    "\n",
    "* In Linux, WSL2: \n",
    "\n",
    "```sh\n",
    "echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bash_profile\n",
    "echo 'export PATH=\"$PATH:~/.local/share/pypoetry/venv/bin\"' >> ~/.bashrc\n",
    "source ~/.bashrc\n",
    "```\n",
    "\n",
    "* In Windows PowerShell \n",
    "\n",
    "```sh\n",
    "[System.Environment]::SetEnvironmentVariable(\"Path\", $env:Path + \";$env:APPDATA\\pypoetry\\venv\\Scripts\", [System.EnvironmentVariableTarget]::User)\n",
    "```\n",
    "\n",
    "* In MacOS:\n",
    "\n",
    "```sh\n",
    "echo 'export PATH=\"$PATH:~/Library/Application Support/pypoetry/venv/bin\"' >> ~/.bash_profile\n",
    "source ~/.bash_profile\n",
    "```\n",
    "\n",
    "You can verify the installation by running \n",
    "\n",
    "```sh\n",
    "poetry --version\n",
    "```\n",
    "\n",
    "Finally, set the the poetry virtual environment to be created inside the repository by running\n",
    "\n",
    "```sh\n",
    "poetry config virtualenvs.in-project true\n",
    "```\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cloning the Repository\n",
    "\n",
    "To clone the repository, follow these steps:\n",
    "\n",
    "1. Open your terminal.\n",
    "\n",
    "2. Navigate to the directory where you want to clone the repository.\n",
    "\n",
    "3. Clone the repository by running the following command:\n",
    "\n",
    "```sh\n",
    "git clone https://github.com/PNNL-CIM-Tools/CIM-Graph.git\n",
    "```\n",
    "If you wish to clone a specific branch, you can specify it with the `-b` option:\n",
    "\n",
    "```sh\n",
    "git clone https://github.com/PNNL-CIM-Tools/CIM-Graph.git -b develop\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Building a Virtual Environment and Wheel\n",
    "\n",
    "After cloning the repository, change directories into CIM-Builder by running\n",
    "\n",
    "```sh\n",
    "cd CIM-Graph\n",
    "```\n",
    "\n",
    "Build the lock file with all requirements needed by running\n",
    "\n",
    "```sh\n",
    "poetry lock\n",
    "```\n",
    "\n",
    "This will also create a python virtual environment in `./CIM-Builder/.venv`. To install CIM-Builder and all dependencies, run\n",
    "\n",
    "```sh\n",
    "poetry install\n",
    "```\n",
    "\n",
    "To use your local CIM-Builder library from other virtual environments, build the wheel and then pip install it from the other environment:\n",
    "\n",
    "```sh\n",
    "poetry build\n",
    "cd ..\n",
    "source ./my_other_env/.venv/bin/activate\n",
    "pip install -e CIM-Graph\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}