Life123 : Dynamical Modeling of Biological Systems
Home1-click Live DemoTechnologyExperimentsGuideVisualizationDiffusionReactionsMembranesDownloadContact / Participate

Download / Install

Nothing to download/install to use the hosted version (live demo)!   Life123 can be TRIED LIVE at Binder, with 1 click!
(say Cancel when asked to include "jupyterlab-dash" in the build!)

Akin to Google's Colab: short-term runs on a hosted JupyterLab environment. Note: A Colab option is also being investigated.

How to Run Locally


Copy the files from the repository to your local machine.

Method 1) On a Linux machine, you can use the command:

    sudo git clone --verbose --config http.sslVerify=false https://github.com/BrainAnnex/life123.git YOUR_LOCAL_DIRECTORY

Method 2) You can download a zip file from the repository

 

Install, if not already present on your machine, Python 3.8+

We currently test on Python 3.8 (earlier versions will NOT work, because of the various libraries.)

Note that Python 3.8 is the last version of python still compatible with Win7.   We currently still support Win7, but that is not expected to last.

 


QUICK-AND-EASY method

We highly recommend using an IDE, such as PyCharm. 

PyCharm will auto-detect the  requirements.txt  file and prompt you to create a virtual environment as specified.

Then:

  1. edit the folder names in the top-level batch file  quick.bat, based on your local folder where you installed Life123 (one-time operation)
  2. just type  quick in the  Terminal tab at the bottom of PyCharm (not to be confused with the "Python Console" tab!)

That's it!  A new browser tab will open, and you can review and run the  experiments  notebooks from within JupyterLab!

For the quick-start method, we set things up with JupyterLab, because we find it much better than Jupyter Notebooks!

    "JupyterLab is the next-generation user interface for Project Jupyter  
    offering all the familiar building blocks of the classic Jupyter Notebook  
    in a flexible and powerful user interface.  
    JupyterLab will eventually replace the classic Jupyter Notebook."

 

Of particular relevance to this project, with JupyterLab, you can easily inspect the HTML log files (with the graphic outputs of program runs):
just right-click on them, and request "Open in New Browser Tab", as shown below:


 

and here's that HTML file from above, viewed in a browser:



OTHER ways to run Life123 (for more advanced users)

SET UP the virtual (local) environment

If you opt to handle setting up the virtual environment yourself, on Linux you can do:

    $ sudo apt install python3.8-venv   (if needed)
    $ python3 -m venv /path_to_root_folder_where_the_files_are/venv
    $ cd source /path_to_root_folder_where_the_files_are
    $ source venv/bin/activate
    (venv) $ pip3 install -r requirements.txt
    (venv) $ deactivate

(or use pipenv or your favorite tool.)

All dependencies (such as NumPy and Jupyter notebooks) are specified in the file  requirements.txt

 

USING the virtual (local) environment

To use the virtual environment’s packages/resources in isolation (i.e. without an IDE), you need to “activate” it. 

To activate the virtual environment:

On Linux:

    $ cd source /path_to_root_folder_where_the_files_are
    $ source venv/bin/activate
    (venv) $       
 

 

On Windows 7, if using the Command Prompt:

    D:    (or whichever drive you copied the files to)
    cd "\path_to_root_folder_where_the_files_are"
    EXAMPLE:  cd "\Docs\- MY CODE\BioSimulations\life123-Win7\"
    
    .\venv\Scripts\activate

    
       You will now see this prompt:
    (venv) DRIVE_LETTER:\path_to_root_folder_where_the_files_are>

 

On Windows 7, if using the PowerShell:

In order to use the PowerShell on Windows7 to run scripts,
one must first run it with admin privileges, and issue the command  Set-ExecutionPolicy unrestricted , and then say  Y  to the prompt  (disregard the complaints about "the setting is overridden by a policy defined at a more specific scope"!)

    D:    (or whichever drive you copied the files to)
    cd "\path_to_root_folder_where_the_files_are"
    EXAMPLE:  cd "\Docs\- MY CODE\BioSimulations\life123-Win7\"
    
    .\venv\Scripts\activate

    
       You will now see this prompt:
    (venv) PS DRIVE_LETTER:\path_to_root_folder_where_the_files_are>

In either case, notice how your prompt is now prefixed with the name of your environment (venv, in our case).  
This is the indicator that venv is currently active, which means the python executable will only use this environment’s packages and settings.

 

Specifying the root path, and running Python scripts

When using an IDE such as PyCharm, the IDE automatically adds the root of the Life123 files  (i.e. the location
of the PyCharm project) to the value of the  sys.path seen inside the execution of the Python files.

If you opt not to use an IDE, or if you're using Jupyter notebooks (such as the ones provided in Life123's  experiments  folder), an extra step is necessary.

IMPORTANT: all steps below are AFTER doing the steps described in the earlier section.
You should be in the local environment, and your prompt should be prefixed by (venv)

On Linux:

    (venv) $ export PYTHONPATH=$PYTHONPATH:`pwd`/venv/lib/python3.8/site-packages
    (NOTE: you might need to change the path /venv/lib/python3.8/site-packages to whatever is on your machine)
    (venv) $ echo $PYTHONPATH 
    [To verify!]

 

On Windows 7, if using the Command Prompt:

set PYTHONPATH=.  will add the  path_to_Life123_root_folder  (the current directory) to the sys.path.

You can verify that it got set, by issuing:  set PYTHONPATH

 

On Windows 7, if using the PowerShell:

$env:PYTHONPATH="."  will add the path_to_Life123_root_folder  (the current directory) to the sys.path.

You can verify that it got set, by issuing:  $env:PYTHONPATH

 



Now, you can issue commands such as:

python experiments/diagnostics.py            (this script will print out sys.path and some other values)
python experiments/life_1D/diffusion/reach_equilibrium.py

Note that setting PYTHONPATH to a dot will NOT work for Jupyter Notebooks (see the next section.)

 

Specifying the root path, and running JupyterLab

IMPORTANT: all steps below are AFTER doing the steps described in the section about activating the virtual environment.

On Windows 7, if using the Command Prompt:

   set PYTHONPATH=\path_to_Life123_root_folder\
  
EXAMPLE:  set PYTHONPATH=\Docs\- MY CODE\BioSimulations\life123-Win7\
     You can verify it, by issuing:  set PYTHONPATH

On Windows 7, if using the PowerShell:

    $env:PYTHONPATH="\path_to_Life123_root_folder\"
    EXAMPLE:  $env:PYTHONPATH="\Docs\- MY CODE\BioSimulations\life123-Win7\"
    You can verify it, by issuing:  $env:PYTHONPATH

Next, start JupyterLab:

    a) jupyter-lab
    OR
    b) jupyter notebook "path_and_name_of_your_desired_notebook"
        EXAMPLE:  jupyter notebook "\Docs\- MY CODE\BioSimulations\life123-Win7\experiments\life_1D\diffusion\reach_equilibrium.ipynb"
    OR
    c)  jupyter notebook --notebook-dir="path_and_name_of_your_desired_startup_folder"
        EXAMPLE:  jupyter notebook --notebook-dir="\Docs\- MY CODE\BioSimulations\life123-Win7\experiments"
        (note: you will not be able to navigate to the parent of the startup folder!)  

Alternatively, the  quick.bat  file could be run, after editing it to specify the name of the local folder and, optionally, to change the requested Jupyter notebook startup folder.

To run it on Windows7 with the command prompt, issue the command:  quick
To run it on Windows7 with the PowerShell, issue the command: .\quick.bat

 



A new browser tab should automatically open.

If you didn't specify the full name of a notebook when starting jupyter (scenario a, above), navigate to the Jupyter notebook of interest. 

The notebooks that are distributed with Life123 are under the  experiments  top-level folder.

If you want to verify that the sys.path is correct, you can add an extra cell to a notebook, and issue the commands:

import sys
sys.path

the result of running those commands should be a list that includes the path_to_Life123_root_folder that you specified.

Note: in case you neglected to set the sys.path when starting Jupyter notebook, you can also set it from within the notebook.
Add a new cell, and run the command: sys.path.append('path_to_Life123_root_folder') .  
Make sure to use double-slashes to represent backslashes in the string.  EXAMPLE:
sys.path.append('D:\\Docs\\- MY CODE\\BioSimulations\\life123-Win7')

 

Ports:

Port 8888 is used by default; if you want a different one,
you can start jupyter notebook with an option such as:

jupyter-lab --port 9999