Download / Install
(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:
- edit the folder names in the top-level batch file
quick.bat, based on your local folder where you installed Life123 (one-time operation) - just type
quickin 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:
$ 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:
$ source venv/bin/activate
(venv) $
On Windows 7, if using the Command Prompt:
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"!)
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:
(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/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:
EXAMPLE: set PYTHONPATH=\Docs\- MY CODE\BioSimulations\life123-Win7\
You can verify it, by issuing: set PYTHONPATH
On Windows 7, if using the PowerShell:
EXAMPLE: $env:PYTHONPATH="\Docs\- MY CODE\BioSimulations\life123-Win7\"
You can verify it, by issuing: $env:PYTHONPATH
Next, start JupyterLab:
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:
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: