notebooks/General description and installation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1b94a59f",
   "metadata": {},
   "source": [
    "# Description\n",
    "PyRN is a library of reaction networks that allows not only to obtain properties of reaction networks, but also to study their evolution. It was created for the purpose of studying the goal-directedness of reaction networks. \n",
    "\n",
    "This documents will show the use of this library. For this purpose, it is divided into several subdocuments, each of which describes a functional part of the library:\n",
    "\n",
    "- Basic use of library.ipynb (pyRN object initialization and basic properties of a reaction network).\n",
    "- Random Network Generation.ipynb (creation of random networks)\n",
    "- Simulator and Random Walks.ipynb (Simulations and random walks by mass action law)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6848a053",
   "metadata": {},
   "source": [
    "## Installation\n",
    "The installation of the library can be done by downloading it from the repository on the page where it is hosted:\n",
    "\n",
    "[https://github.com/pmaldona/pyRN](https://github.com/pmaldona/pyRN)\n",
    "\n",
    "This can be done by clicking the <span style=\"color:green\">*Code*</span> tab, and the clicking *Download zip*.\n",
    "\n",
    "Another alternative can be done by cloning the repository using git:\n",
    "\n",
    "    $ git clone https://github.com/pmaldona/pyRN\n",
    "\n",
    "Once downloaded the library can be locally installed using the following command in the path where the library was downloaded or unzipped:\n",
    "\n",
    "    $ python pip install .\n",
    "\n",
    "### Linux requirements\n",
    "pyRN require the installation of the lxml library, in Debian/Ubuntu can be installed by:\n",
    "\n",
    "    $ sudo apt-get install libxml2-dev libxslt-dev python-dev\n",
    "\n",
    "Please refer to https://lxml.de/installation.html for other systems.\n",
    "\n",
    "It also require some packages to run the pypoman library, in Debian/Ubuntu can be installed by:\n",
    "\n",
    "    $ sudo apt-get install cython libglpk-dev\n",
    "    \n",
    "## Windows\n",
    "\n",
    "The lxml library requires certain binaries that can be downloaded and then installed, these can be obtained from the following link:\n",
    "\n",
    "[http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml](http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml)\n",
    "\n",
    "## MacOS-X\n",
    "\n",
    "On MacOS-X, use the following to build the source distribution, and make sure you have a working Internet connection, as this will download libxml2 and libxslt in order to build them:\n",
    "\n",
    "    STATIC_DEPS=true sudo pip install lxml\n",
    "    \n",
    "### `pyRN` library installation procedure on Mac Arm based processors:\n",
    "\n",
    "`pyRN` library installation generates errors when installed via `pip`. In particular one of the dependencies, the `pypoman` package, presents problems in the secondary dependencies `pycddlib` and `cvxopt`.\n",
    "\n",
    "\n",
    "Error installing pycddlib package via `pip`:\n",
    "```\n",
    "fatal error: 'gmp.h' file not found.\n",
    "#include \"gmp.h\"\n",
    "^~~~~~~\n",
    "1 error generated.\n",
    "error: command '/usr/bin/clang' failed with exit code 1\n",
    "```\n",
    "Error installing cvxopt package via `pip`:\n",
    "```\n",
    "fatal error: 'umfpack.h' file not found.\n",
    "#include \"umfpack.h\"\n",
    "^~~~~~~~~~~\n",
    "1 error generated.\n",
    "error: command '/usr/bin/clang' failed with exit code 1\n",
    "```\n",
    "\n",
    "#### Error resolution with pycddlib package\n",
    "\n",
    "The gmp library is necessary for the correct operation of pycddlib, for this reason it is first necessary to install it:\n",
    "\n",
    "`brew install gmp`.\n",
    "\n",
    "Once installed, the homebrew libraries location directory must be exported, so that when pycddlib is compiled, it can be found by the compiler.\n",
    "\n",
    "`export LIBRARY_PATH=/opt/homebrew/lib`.\n",
    "\n",
    "is finally installed with the corresponding path for the compiler options:\n",
    "\n",
    "`CFLAGS=-I/opt/homebrew/opt/gmp/include\n",
    "LDFLAGS=-L/opt/homebrew/opt/gmp/lib\n",
    "pip install pycddlib`\n",
    "\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d50d4515",
   "metadata": {},
   "source": [
    "## Nomenclature:\n",
    "\n",
    "For the correct identification of the Variables and functions of the library there is a tag for the identification of different objects used. There are two categories of clasification, one are the nomenclature used to classified the ontology of role in the theory. On the other hand, there is a ontology type reference objects and the role perfomed by a function. The nomeclature goes as\n",
    "###  Ontology of the theory (Organization Theory)\n",
    "\n",
    "#### Fundamental entities:\n",
    "\n",
    "| Concept                                 | Name             |\n",
    "|-----------------------------------------|------------------|\n",
    "| Species                                 | `Sp`             |\n",
    "| Reactions                               | `Rp`             |\n",
    "| Reactive stoichiometric matrix          | `Mp`             |\n",
    "| Productive stoichiometric matrix        | `Mr`             |\n",
    "| Stoichiometric matrix                   | `S`              |\n",
    "| Generators                              | `G`              |\n",
    "| Basic molecules                         | `B`              |\n",
    "| Atoms                                   | `A`              |\n",
    "| Synergies                               | `Syn`            |\n",
    "| Minimal generators                      | `Mgen`           |\n",
    "| Reaction network                        | `Rn`             |\n",
    "\n",
    "#### Fundamental properties:\n",
    "\n",
    "| Concept                                      | Name               |\n",
    "|----------------------------------------------|--------------------|\n",
    "| Reactive part (reaction or synergiers)       | `Reac`             |\n",
    "| Productive part (reaction or synergiers)     | `Prod`             |\n",
    "| Stoichiometric Positive                      | `StoichioPositive` |\n",
    "| Stoichiometric Negative                      | `StoichioNegative` |\n",
    "| Inflow                                       | `Inflow`           |\n",
    "| Outflow                                      | `Outflow`          |\n",
    "| Closure                                      | `Closed`           |\n",
    "| Semi-self-maintianed                         | `Ssm`              |\n",
    "| Self-maintianed                              | `Sm`               |\n",
    "| Connected (via reactions)                    | `Connected`        |\n",
    "| Mass Action Kinetics                         | `Mak`              |\n",
    "| Concentration (for species)                  | `Con`              |\n",
    "| Rate (for reactions)                         | `Rate`             |\n",
    "| Abstraction                                  | `Abstrac`          |\n",
    "| Active                                       | `Active`           |\n",
    "| Dynamic Model                                | `Model`            |\n",
    "| Dynamic Model parameters                     | `Pram`             |\n",
    "| Perturbation                                 | `Pert`             |\n",
    "| State (related to the perturbation)          | `State`            |\n",
    "| Activation (related to the perturbation)     | `Activation`       |\n",
    "| Randomiization (related to the perturbation) | `Randomize`        |\n",
    "| Random Walk                                  | `Rw`               |\n",
    "\n",
    "###  Ontology of type reference (library variables and functions roles)\n",
    "\n",
    "#### Variables:\n",
    "\n",
    "| Concept                                 | Name             |\n",
    "|-----------------------------------------|------------------|\n",
    "| Numpy array                             | `Array`          |\n",
    "| Pandas dataframe                        | `Df`             |\n",
    "| Bitarray                                | `Bt`             |\n",
    "| Networkx multigraph                     | `Nx`             |\n",
    "| List                                    | `List`           |\n",
    "| Dictionary                              | `Dict`           |\n",
    "| Sting                                   | `Str`            |\n",
    "| Pyvis object                            | `Pv`             |\n",
    "| Smbl file                               | `Smbl`           |\n",
    "| Text file                               | `Text`           |\n",
    "| Filename                                | `Filename`       |\n",
    "\n",
    "\n",
    "#### Function Roles:\n",
    "\n",
    "| Concept                                           | Name               |\n",
    "|---------------------------------------------------|--------------------|\n",
    "| Generate library member                           | `set`              |\n",
    "| return an object                                  | `get`              |\n",
    "| Plot                                              | `plot`             |\n",
    "| Display (normally a pyvis object)                 | `display`          |\n",
    "| Print (on console)                                | `print`            |\n",
    "| From                                              | `From`             |\n",
    "| To                                                | `to` or `To`       |\n",
    "| Is                                                | `is` or `Is`       |\n",
    "| No                                                | `No`               |\n",
    "| With                                              | `With`             |\n",
    "| Generate (for internal functions)                 | `gen`              |\n",
    "| recursive (for internal functions)                | `recursive`        |\n",
    "| run (olnly for dynamic model)                     | `run`              |\n",
    "| In addtion to (use for random generated networks) | `Extra`              |\n",
    "\n",
    "The syntax of any member of the library distinguished his ontoloy by capital letters. In addition, all functions start with lowercase letters while member objects start with capital letters. For example:\n",
    "\n",
    "- `RN.isSmFromSp()` corresponds to a function that checks whether a set of species is self-maintained.\n",
    "\n",
    "- `RN.BListBtSp` corresponds to a list of species bitarrays of the basic molecules.\n",
    "\n",
    "It is worth noting that the nomenclature has a nesting structure, it descends the characteristics of these, first to which object itself, then which sub onject correspond and how the varaible is strucutred."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}