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.
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:
quick.bat
, based on your local folder where you installed Life123 (one-time operation)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:
SET UP the virtual (local) environment
If you opt to handle setting up the virtual environment yourself, on Linux you can do:
(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:
On Windows 7, if using the Command Prompt:
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"!)
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:
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:
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:
On Windows 7, if using the PowerShell:
Next, start JupyterLab:
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:
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: