Difference between revisions of "Getting Started"

From Biocellion
Jump to: navigation, search
m (Bash variable assignments must not have spaces around the = operator.)
m (.vid -> .vdi)
 
(21 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
There are three options to set up a Biocellion environment. They are all available for download on the Biocellion [http://biocellion.com/download/ Download] page.
+
There are three options to set up a Biocellion environment. They are all available for download on the Biocellion [http://download.biocellion.com/download Download] page (updated for Biocellion 1.2 03/27/2017).
  
 
# Download Biocellion VirtualBox Disk Image (.vdi) and run on [https://www.virtualbox.org/wiki/Downloads VirtualBox]
 
# Download Biocellion VirtualBox Disk Image (.vdi) and run on [https://www.virtualbox.org/wiki/Downloads VirtualBox]
Line 6: Line 6:
 
# Directly download Biocellion from Biocellion.com and set up your own environment
 
# Directly download Biocellion from Biocellion.com and set up your own environment
  
If you are a new user who wants to try out Biocellion, you may want to choose option 1. The VirtualBox Disk Image has all the necessary softwares and environment preset to easily get started on Biocellion. However, this option may suffer from slower performance, and high memory usage. The VirtualBox Disk Image is about 3GB in size compressed, and 8 GB in size uncompressed.  
+
If you are a new user who wants to try out Biocellion, you may want to choose option 1. The VirtualBox Disk Image has all the necessary softwar and environment preset to easily get started on Biocellion. However, this option may suffer from slow performance, and high memory usage. The VirtualBox Disk Image is about 3GB in size compressed, and 8 GB in size uncompressed.  
  
If you are a competent *nix language user and wish to set up Biocellion on the cloud, you may choose option 2. Google Cloud currently offers 2 months of free trial ($300 credit) for up to 8 virtualCPUs of compute power. This may be a desirable option if you wish to take advantage of Biocellion’s parallel-computing capability. The Google Cloud option does not come with Paraview as it does in option 1.  
+
If you are a competent *nix user and wish to set up Biocellion on the cloud, you may choose option 2. Google Cloud currently offers 2 months of free trial ($300 credit) for up to 8 virtualCPUs of compute power. This may be a desirable option if you wish to take advantage of Biocellion’s parallel-computing capability. The Google Cloud option does not come with Paraview as it does in option 1.  
  
 
Finally, you may choose to set up Biocellion locally by simply downloading from Biocellion.com You would need to separately download Intel Threading Building Blocks 4.4 and optionally, Paraview. Additionally, several local directory paths would have to be preconfigured before running Biocellion.
 
Finally, you may choose to set up Biocellion locally by simply downloading from Biocellion.com You would need to separately download Intel Threading Building Blocks 4.4 and optionally, Paraview. Additionally, several local directory paths would have to be preconfigured before running Biocellion.
Line 15: Line 15:
 
[[File:Getting Started 1.png | thumb|VirtualBox Setup Step 4]]
 
[[File:Getting Started 1.png | thumb|VirtualBox Setup Step 4]]
 
[[File:Getting Started 3.png|thumb|VirtualBox Setup Step 6]]
 
[[File:Getting Started 3.png|thumb|VirtualBox Setup Step 6]]
1. Download and unzip Biocellion VirtualBox Disk Image (.vid) from Biocellion Download page. <br />
+
1. Download and unzip Biocellion VirtualBox Disk Image (.vdi) from Biocellion Download page. <br />
  
 
2. If you have not done so already, download and install the appropriate version of [https://www.virtualbox.org/wiki/Downloads VirtualBox] for your OS. <br />  
 
2. If you have not done so already, download and install the appropriate version of [https://www.virtualbox.org/wiki/Downloads VirtualBox] for your OS. <br />  
Line 31: Line 31:
 
8. On the Desktop, there is a directory named ‘'''BiocellionVirtualBox'''’. It contains three subdirectories: biocellion, tbb44_20160526oss, and ParaView-5.1.0-Qt4-OpenGL2-MPI-Linux-64bit. [Update: now has Paraview-4.1.0]<br />
 
8. On the Desktop, there is a directory named ‘'''BiocellionVirtualBox'''’. It contains three subdirectories: biocellion, tbb44_20160526oss, and ParaView-5.1.0-Qt4-OpenGL2-MPI-Linux-64bit. [Update: now has Paraview-4.1.0]<br />
  
9. '''biocellion''' directory contains the Biocellion software. Biocellion is already configured for easy use. However, if the user wishes to move the location of the software, you must edit the BIOCELLION_ROOT path in '''Makefile.common'''. All of the actual model coding will take place in '''libmodel/''' directory. Simulation is run in '''framework/main/''' directory. <br />
+
9. '''biocellion1.2''' directory contains the Biocellion software. Edit the BIOCELLION_ROOT path in '''Makefile.model''' to where the main Biocellion model directory is. All of the model codes take place in '''biocellion-user/''' directory. In '''biocellion1.2''', the directory structure has been modified to facilitate enterprise installation, where users read-only access to a shared instance of Biocellion.<br />
  
 
10. '''ParaView-4.1.0-Linux-64bit''' directory contains the ParaView software for visualizing Biocellion model outputs. More information on Paraview can be found here.<br />
 
10. '''ParaView-4.1.0-Linux-64bit''' directory contains the ParaView software for visualizing Biocellion model outputs. More information on Paraview can be found here.<br />
  
11. '''tbb44_20160526oss''' (Threading Building Blocks) is C++ template library for parallel programming. Biocellion depends on tbb44, so change in the current set up is not recommended. If the user wishes to move the tbb44_20160526oss directory, the '''LD_LIBRARY_PATH''' in '''~/.profile''' must be edited as well.<br />
+
11. The virtual machine has the 2017 version of Threading Building Blocks (C++ template library for parallel programming): '''tbb442017_20161128oss'''. If the user wishes to move (or update) the TBB library, the '''LD_LIBRARY_PATH''' in '''~/.profile''' must be edited as well.<br />
  
 
12. You’re ready to start running Biocellion!<br />
 
12. You’re ready to start running Biocellion!<br />
Line 41: Line 41:
 
== Option 2: Setup Google Cloud and Copy the Virtual Image Instance ==
 
== Option 2: Setup Google Cloud and Copy the Virtual Image Instance ==
  
1. Download the zipped gcloud Disk Image from Biocellion Download page.<br />
+
1. Download the gcloud Disk Image from Biocellion Download page (latest version: Biocellion1.2_GoogleCloudImage.1.12.2018.tar.gz). Do not unzip.<br />
  
2. Install [https://cloud.google.com/sdk/docs/quickstarts Google Cloud SDK] in your local environment. [https://cloud.google.com/sdk/docs/configurations Configure user] and create a <nowiki><project-name></nowiki> in [https://console.cloud.google.com/ Google Cloud Console]<br />
+
2. Install [https://cloud.google.com/sdk/docs/quickstarts Google Cloud SDK] in your local environment. [https://cloud.google.com/sdk/docs/configurations Configure user] and create a new project in [https://console.cloud.google.com/ Google Cloud Console]<br />
  
3. In your Google Cloud Console, create a bucket in Google Cloud Storage and in that bucket, upload the zipped image (do not unzip)  “myimage.tar.gz” to Google Cloud Storage.<br />
+
3. In your Google Cloud Console, create a bucket in Google Cloud Storage and in that bucket, upload the gcloud Disk Image to Google Cloud Storage.<br />
  
4. Once the zipped image is uploaded to Google Cloud Storage, run the following command in Terminal:
+
4. Once the Disk Image is uploaded to Google Cloud Storage, run the following command in Terminal:
 
         gcloud compute images create <nowiki><project-name></nowiki> --source-uri <nowiki><URI></nowiki>
 
         gcloud compute images create <nowiki><project-name></nowiki> --source-uri <nowiki><URI></nowiki>
<nowiki><URI></nowiki> is the link to the zipped image in your Google Cloud Storage (i.e. "enter address" if your bucket name is “biocellion_test_1”. Everyone should have a unique bucket name.)<br />
+
<nowiki><URI></nowiki> is the location to the zipped Disk Image in your Google Cloud Storage (i.e. your URI may be https://storage.googleapis.com/bucket-name/Biocellion1.2_GoogleCloudImage.1.12.2018.tar.gz if you named your bucket, “bucket-name”.) <br />
  
 
5. Now, the image <nowiki><project-name></nowiki> should be available under Images in your Google Cloud Platform. Create a virtual-machine instance booting from your image <nowiki><project-name></nowiki>.<br />
 
5. Now, the image <nowiki><project-name></nowiki> should be available under Images in your Google Cloud Platform. Create a virtual-machine instance booting from your image <nowiki><project-name></nowiki>.<br />
Line 57: Line 57:
 
It may ask you to set up an ssh key. <br />
 
It may ask you to set up an ssh key. <br />
  
7. Logging in as “bio” to access Biocellion:
+
7. Log in as “bio” to access Biocellion:
 
         su bio
 
         su bio
 
         password: bio
 
         password: bio
 
         cd ~/
 
         cd ~/
  
8. Enable Threading. Threading must be enabled each time you connect to gcloud to run Biocellion:
+
8. You're ready to start coding! Place all Biocellion models under the 'biocellion-user' directory.<br />
        cd ~/tbb44_20160526oss/bin/g
 
        . ./tbbvars.sh intel64
 
 
 
9. You’re ready to start running Biocellion!<br />
 
  
 
== Option 3: Directly Download Biocellion from Biocellion.com and Set Up Your Own Environment ==
 
== Option 3: Directly Download Biocellion from Biocellion.com and Set Up Your Own Environment ==
Line 73: Line 69:
 
1. Download Biocellion from Biocellion.com. Unzip Biocellion.<br />
 
1. Download Biocellion from Biocellion.com. Unzip Biocellion.<br />
  
2. Open Makefile.common. Edit BIOCELLION_ROOT = /home/kang697/biocellion-1.1 to the directory where Biocellion was installed.<br />
+
2. Open Makefile.model in the biocellion-user/ directory. Edit BIOCELLION_ROOT = /home/kang697/biocellion-1.2 to the directory path where Biocellion was installed.<br />
 +
 
 +
3. Download Intel TBB (Threading Building Blocks version 2017 update 2 or later) from [https://www.threadingbuildingblocks.org/download threadingbuildingblocks.org]. Unzip.<br /> Alternatively, Ubuntu users can install Intel TBB with:
 +
    sudo apt-get install libtbb2
  
3. Download Intel TBB (Threading Building Blocks) from threadingbuildingblocks.org. Unzip.<br />
+
4. Add TBB_ROOT(the directory where you unzipped Intel TBB)/lib/intel64/gcc4.4 and the Biocellion model directory path to LD_LIBRARY_PATH. You can do this by typing (if you’re using GNU Bash) the following line in Terminal:
 +
      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:TBB_ROOT(the directory where you unzipped intel TBB)/lib/intel64/gcc4.4:/BIOCELLION_ROOT(the Biocellion directory)/biocellion-user/model
  
4. Add TBB_ROOT(the directory where you unzipped Intel TBB)/lib/intel64/gcc4.4 to LD_LIBRARY_PATH. You can do this by typing (if you’re using GNU Bash) the following line in Terminal:
+
This adds TBB for only the current Terminal session in which you are running Biocellion. If you would like LD_LIBRARY_PATH to permanently point TBB_ROOT, you may add the same export line at the bottom of the ~/.profile file.  <br />
      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:TBB_ROOT(the directory where you unzipped intel TBB)/lib/intel64/gcc4.4
 
This adds gcc4.4 TBB for only the current Terminal session in which you are running Biocellion. If you would like LD_LIBRARY_PATH to permanently point TBB_ROOT, you may add the same export line at the bottom of the ~/.profile file.  <br />
 
  
5. You’re ready to start running Biocellion!  
+
5. You’re ready to start running Biocellion!
  
 
== Next Tutorial ==
 
== Next Tutorial ==
  
 
[[Building_the_First_Model|Building the First Model]]
 
[[Building_the_First_Model|Building the First Model]]

Latest revision as of 00:04, 2 February 2019

Introduction

There are three options to set up a Biocellion environment. They are all available for download on the Biocellion Download page (updated for Biocellion 1.2 03/27/2017).

  1. Download Biocellion VirtualBox Disk Image (.vdi) and run on VirtualBox
  2. Download Biocellion gcloud Disk Image and Setup Google Cloud and copy the Virtual Image Instance
  3. Directly download Biocellion from Biocellion.com and set up your own environment

If you are a new user who wants to try out Biocellion, you may want to choose option 1. The VirtualBox Disk Image has all the necessary softwar and environment preset to easily get started on Biocellion. However, this option may suffer from slow performance, and high memory usage. The VirtualBox Disk Image is about 3GB in size compressed, and 8 GB in size uncompressed.

If you are a competent *nix user and wish to set up Biocellion on the cloud, you may choose option 2. Google Cloud currently offers 2 months of free trial ($300 credit) for up to 8 virtualCPUs of compute power. This may be a desirable option if you wish to take advantage of Biocellion’s parallel-computing capability. The Google Cloud option does not come with Paraview as it does in option 1.

Finally, you may choose to set up Biocellion locally by simply downloading from Biocellion.com You would need to separately download Intel Threading Building Blocks 4.4 and optionally, Paraview. Additionally, several local directory paths would have to be preconfigured before running Biocellion.

Option 1: Download Biocellion VirtualBox Disk Image and Run on VirtualBox

VirtualBox Setup Step 4
VirtualBox Setup Step 6

1. Download and unzip Biocellion VirtualBox Disk Image (.vdi) from Biocellion Download page.

2. If you have not done so already, download and install the appropriate version of VirtualBox for your OS.

3. Create a new virtual machine by clicking from the menu, Machine > New.

4. Name your virtual machine, select ‘Linux’ for Type, and ‘Ubuntu (64-bit). Continue.

5. Allocate memory. Continue.

6. Select ‘Use an existing virtual hard disk file,’ and load the uncompressed Biocellion.vdi file. Create.

7. Now, the new Virtual Machine will be available on the left panel of VirtualBox. Start the Virtual Machine. This machine has default login username of “Biocellion” and password “bio”. The user may choose to change the login setting. [Update: no password is required]

8. On the Desktop, there is a directory named ‘BiocellionVirtualBox’. It contains three subdirectories: biocellion, tbb44_20160526oss, and ParaView-5.1.0-Qt4-OpenGL2-MPI-Linux-64bit. [Update: now has Paraview-4.1.0]

9. biocellion1.2 directory contains the Biocellion software. Edit the BIOCELLION_ROOT path in Makefile.model to where the main Biocellion model directory is. All of the model codes take place in biocellion-user/ directory. In biocellion1.2, the directory structure has been modified to facilitate enterprise installation, where users read-only access to a shared instance of Biocellion.

10. ParaView-4.1.0-Linux-64bit directory contains the ParaView software for visualizing Biocellion model outputs. More information on Paraview can be found here.

11. The virtual machine has the 2017 version of Threading Building Blocks (C++ template library for parallel programming): tbb442017_20161128oss. If the user wishes to move (or update) the TBB library, the LD_LIBRARY_PATH in ~/.profile must be edited as well.

12. You’re ready to start running Biocellion!

Option 2: Setup Google Cloud and Copy the Virtual Image Instance

1. Download the gcloud Disk Image from Biocellion Download page (latest version: Biocellion1.2_GoogleCloudImage.1.12.2018.tar.gz). Do not unzip.

2. Install Google Cloud SDK in your local environment. Configure user and create a new project in Google Cloud Console

3. In your Google Cloud Console, create a bucket in Google Cloud Storage and in that bucket, upload the gcloud Disk Image to Google Cloud Storage.

4. Once the Disk Image is uploaded to Google Cloud Storage, run the following command in Terminal:

       gcloud compute images create <project-name> --source-uri <URI>

<URI> is the location to the zipped Disk Image in your Google Cloud Storage (i.e. your URI may be https://storage.googleapis.com/bucket-name/Biocellion1.2_GoogleCloudImage.1.12.2018.tar.gz if you named your bucket, “bucket-name”.)

5. Now, the image <project-name> should be available under Images in your Google Cloud Platform. Create a virtual-machine instance booting from your image <project-name>.

6. Now, you should have a virtual machine running on Biocellion Image. Run gcloud locally in Terminal by typing:

       gcloud compute --project “<your project>” ssh --zone “<zone>” “<your-instance>”

It may ask you to set up an ssh key.

7. Log in as “bio” to access Biocellion:

       su bio
       password: bio
       cd ~/

8. You're ready to start coding! Place all Biocellion models under the 'biocellion-user' directory.

Option 3: Directly Download Biocellion from Biocellion.com and Set Up Your Own Environment

(source from Biocellion Support Forum)

1. Download Biocellion from Biocellion.com. Unzip Biocellion.

2. Open Makefile.model in the biocellion-user/ directory. Edit BIOCELLION_ROOT = /home/kang697/biocellion-1.2 to the directory path where Biocellion was installed.

3. Download Intel TBB (Threading Building Blocks version 2017 update 2 or later) from threadingbuildingblocks.org. Unzip.
Alternatively, Ubuntu users can install Intel TBB with:

   sudo apt-get install libtbb2

4. Add TBB_ROOT(the directory where you unzipped Intel TBB)/lib/intel64/gcc4.4 and the Biocellion model directory path to LD_LIBRARY_PATH. You can do this by typing (if you’re using GNU Bash) the following line in Terminal:

     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:TBB_ROOT(the directory where you unzipped intel TBB)/lib/intel64/gcc4.4:/BIOCELLION_ROOT(the Biocellion directory)/biocellion-user/model

This adds TBB for only the current Terminal session in which you are running Biocellion. If you would like LD_LIBRARY_PATH to permanently point TBB_ROOT, you may add the same export line at the bottom of the ~/.profile file.

5. You’re ready to start running Biocellion!

Next Tutorial

Building the First Model