View source for STEM Installation Guide

[[Image:STEM TOP BAR.gif|800px]]


{| align="left"
  | __TOC__
  |}


<br clear=all>

'''[[STEM|Back to STEM Contents Page]]''' 



== STEM Video on YouTube<sup>TM</sup> ==
The STEM Project published full-length video tutorials for STEM on YouTube in several languages.

#[http://www.youtube.com/watch?v=MtQlS7g7Qnw STEM Model Generator (new!!)] ''requires STEM V2.0 milestone''
#Full length video [http://www.youtube.com/watch?v=LfiibQX4IFE In English] 
#Full length video [http://www.youtube.com/watch?v=AFYXvazKkms In Hebrew] 
#Full length video [http://www.youtube.com/watch?v=NM5X8-MaiKo In Japanese] 
#Full length video [http://www.youtube.com/watch?v=3S5DbjCHsx4 In Spanish] 
#[http://www.youtube.com/watch?v=OoiFLemepw4 5 min Video (English)]
#Avian Influenza
##Only [https://youtu.be/tI0Ogy-8O10 Poultry-Human Transmission] 
##Including  [https://youtu.be/0YJ6FxdhFm8 Human-Human Transmission]

== Getting Started ==
There are two paths to running STEM:  from a downloaded binary installed as a standalone application or built from source and launched in Eclipse.  Here are some considerations regarding which path to choose:

* If you want to use STEM to compose models, scenarios, and run simulations, you can download and install STEM as a standalone application following the instructions in this guide.
* If you want to extend or add new functionality to STEM, including new disease and computational models, you need to build STEM from source.  See the [[STEM_Eclipse_Setup|Setting up a STEM Development Environment]] page for more instructions.

=== Issue with macOS Big Sur ===
We are currently debugging several issues caused by the macOS Update to Big Sur. Please watch this page for updates.
One Condition we observed is as follows. 
After Downloading the integration build Mac will report that the Application is broken and can not be opened.
If you see this, open a terminal window and navigate to your Applicaitons folder
Issue the following command:
 xattr com.apple.quarantine STEM.app 
 (or whatever you named the application, eg. STEM_integration_2_1_21.app)
If you see
 com.apple.quarantine
Then issue the following
 xattr -d com.apple.quarantine STEM.app
Then test again by 
 xattr com.apple.quarantine STEM.app 
This does not fix all issues but will remove the quarantine issue. Please watch this page for updates.

=== Prerequisites ===
STEM is a Java application built on top of the Eclipse Rich Client Platform (RCP).  To run STEM, please verify you have the following prerequisites installed:

# A workstation running an Eclipse-supported operating system:
#* Windows 64bit  (XP, Vista, 7,8,10)
#* Linux (GTK)
#* Mac OS X (10.5 or later)
#* STEM V4.0.3 and higher include the required Java SE
# A tool to extract zipped archives
#: ''Most operating systems have this built-in, although Windows users may wish to install a standalone utility like [http://www.7-zip.org/ 7-Zip]''

=== Which File To Download? ===
The STEM Project publishes several different binary versions of the application.  Please consider these options when choosing which to download.

==== 32-bit vs. 64-bit ====
As of STEM V4.0.3 and higher, we only support 64-bit (x86_64) compiled binaries.  
The 64-bit version of STEM can take advantage of larger memory spaces (beyond 2 GB), which is necessary to run very large (global) simulations.
''' The version you download requires you have a 64-bit Java Runtime Environment (JRE) installed. '''  
Some 64-bit JREs can run in 32-bit mode.  Please see your JRE's documentation for instructions.

==== Release, Milestone, or Integration Builds ====
The best version of STEM to download is generally the latest '''Release'''.  In addition to being fully tested and stable, it's approved for distribution by the Eclipse Foundation and subject to the terms of the [http://www.eclipse.org/legal/epl/notice.php Eclipse Software User Agreement] and the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License].

However, power users or those looking for the latest features may choose to download the latest '''Weekly Integration''', '''Milestone''', or '''Release Candidate''' build.  These builds may not be stable and are not sanctioned by the Eclipse Foundation.  ''Use at your own risk''.

== Downloading and Installing STEM ==
The STEM application is bundled as a platform-specific, zipped archive and does not contain an installer.  To install STEM, download the appropriate bundle and unzip it to your desired installation path. Please observe:

 <span style="color:#ff0000">'''The STEM installation path cannot contain whitespace characters.  Ensure that the install path contains no spaces, tabs, etc.'''</span>

''' If you already have STEM 1.4 or newer installed and wish to upgrade, see the [[#STEM_Updates|STEM Updates section]]. '''

# In your browser, go to the '''[http://www.eclipse.org/stem/downloads.php STEM Downloads page]'''
# Choose the appropriate bundle to download (see [[#Which_File_To_Download.3F|previous section]] for help) and click the link
# On the mirrors page, select a nearby mirror site.  This will begin the download.
# If prompted, choose to '''Save''' the file.  Note where the file is downloading to.
#: '' On some systems, the browser may automatically execute (unzip) the file when it finishes downloading.  If this is the case, skip to '''step 8''' when the download finishes. ''
# ''Wait while the STEM bundle downloads...''
#:  '' '''Note:''' STEM is approximately 150 MB in size.  Depending on your connection and mirror speeds, the download will take from a few minutes to an hour or more. ''
# When the download finishes, open the folder where the downloaded file sits
# Extract/unzip the STEM archive
#: '' '''Note:''' On most systems, double clicking the the .zip file will automatically extract it. ''
# Extracting the archive should create a folder called '''stem'''.  Move this folder to the path you wish to install STEM at.
#: '' ''' IMPORTANT REMINDER: ''' Verify that the install path does not contain whitespace or non-ASCII characters, including spaces, tabs, etc. ''
#* Windows users may want to place '''stem''' folder in a drive root.  Example is '''c:\stem'''
#* Mac OS X users must to place the '''stem''' folder in the '''Applications''' folder
# Optionally, you can create a shortcut on your desktop, start menu, dock, etc to quickly launch STEM
# Increasing the system memory available to STEM. Some large scenarios (e.g. with thousands of nodes and edges), require that you make sure you allocate enough system memory for STEM. If you don't do this the application may hang or crash with a "Heap Space" error. To allocate enough memory:
#* On Windows, create a shortcut for launching STEM. You may place this anywhere (e.g., on your desktop or on the quicklaunch bar). 
## Right click on the shortcut. Select "Properties" You should see a field in the Properties Dialogue labeled Target: to the right in the text field you will see something like:
##* C:\stem_builds\stem\STEM.exe
## To launch STEM with more memory you must add "virtual machine arguments" to the target line. For example, to set the min heap size to 1 GB and max heap size to 4GB use: 
##* C:\stem_builds\stem\STEM.exe -vmargs -Xms1024M -Xmx4096M -XX:PermSize=256m -XX:MaxPermSize=512m
#* On MAC OS X, using the finder, navigate to where the STEM application (eg your Applications folder)
##Right click on the STEM.app icon
##select Show Package Contents
##navigate to >Contents>Eclipse
##Open the STEM.ini file
##Change the -Xms and the -Xmx lines to increase the memory, e.g. -Xms1024M -Xmx4096M or more depending on how much memory is available. ''For example:''
###-Xms512m
###-Xmx4096m 
###-XX:PermSize=256m
###-XX:MaxPermSize=512m
 



That's it!  STEM is now installed.  See the next section for instructions to launch STEM.

== Security Settings in Mac OSx Mojave ==

Mojave has new security control features that can make it challenging to install applications and get them to run.
If you get an error launching STEM follow the instructions below.

1. Make sure you dragged the extracted STEM.app to the Applications folder
2. open a console. Enter the following command to temporarily disable Apple Gatekeeper

 sudo spctl --master-disable

3. Open "System Preferences", click on “Security & Privacy” and check under the General tab.
4. Unlock the settings by clicking on the padlock and entering your password.
5. Where it is written, “Allow apps downloaded from:” you will now see a third option: “Anywhere”. Select this and click on the padlock icon to save the changes.

6. Open "System Preferences", click on “Security & Privacy” and check under the Privacy tab.
7. Unlock the settings by clicking on the padlock and entering your password
8. UNDER the panel labeled "Allow the apps below to control your computer" click the + button
9. Navigate to STEM.app in the Applications folder and add it to the list.
10. Check for the checkbox to Allow
11. click on the padlock icon to save the changes

== Launching and Running STEM ==
After STEM is unzipped and placed in the install folder, you can launch the application. STEM can run both with a full Graphical User Interface (GUI) or "headlessly" in a text-only console.  For more information about the text-only option, see the [[STEM Headless|headless STEM article]].

# Navigate to the folder STEM is installed in
# Double click the STEM executable file
#: [[Image:STEM-Install-FinderView.png|400px]]
#* For Windows, the file is named '''STEM.exe'''
#* For Mac OS X, the file is named '''STEM''' or '''STEM.app'''
#* For Linux, the file is named '''STEM'''
# On some system, you may get a security warning about launching a downloaded application.  Click '''OK''' or '''Open'''
#: '' '''Note:''' This warning message varies depending on your operating system ''
#: [[Image:STEM-Install-DownloadedApplicationWarning.png|200px]]
# The STEM splash screen should immediately appear
#: [[Image:STEM-Install-Splash.png|200px]]
# The first time STEM is launched, several configuration tasks have to run in the background
#: ''These tasks may take 1-2 minutes depending on system speed.  During this time, only the splash screen is displayed.''
# When STEM finishes loading, the workbench will launch the '''Simulation''' perspective
#: The first time you run STEM, the '''Welcome to STEM''' screen will display.  You can close this by click the '''X''' on the '''Welcome''' tab.
#: [[Image:STEM-Install-WelcomeScreen.png|200px]]
# Congratulations! STEM is loaded and ready to use
#: [[Image:STEM-Install-Workbench.png|500px]]
# To get started using STEM, start by going through the tutorials on the [[STEM#STEM_Documentation|STEM Documentation]] page
#: '' You may find it helpful to watch the [http://www.youtube.com/watch?v=LfiibQX4IFE YouTube tutorial] before you go on to learn to [[Creating_a_STEM_Scenario|create a scenario]] ''

== Configure STEM Preference ==

Next you should configure STEM runtime preferences. After launch, on the menu bar,
# on mac go to >STEM>Preferences>General  and check the box '''Show heap status''' so you can see how much memory is being used (just like any Eclipse Application).
#* on windows the path is >Windows>Preferences>General
# Next go to >STEM>Preferences>STEM>Solver or >Windows>Preferences>STEM>Solver
#* You can change the '''Number of concurrent worker threads'''. Don't set this higher than the number of core on your machine.
# Next go to >STEM>Preferences>STEM>Simulation Management or >Windows>Preferences>STEM>Simulation Management
#* Note that by default the checked box ''Pause simulation after each cycle'', and the default value of ''100  Milliseconds to pause each cycle''. You can change this value or uncheck the box to make STEM run faster. If you want to ''see'' the simulation run (e.g., using STEM for demos) then the default pause setting is probably ok. You can adjust this parameter based on your needs.
# Look at the other STEM configuration settings. You can customize a number of features.


==Installing Additional STEM Features== 
: '' See section on [[STEM Addons | STEM Add-ons]] ''

STEM uses the Automated Eclipse Updates to make it easier for users to install additional features to STEM. Today, one feature you may want to add
is the Earth Science data plugin that contains global climate data for the years 2001-2010. This plugin is '''required''', for example, if you want to use the ''Anopheles'' Mosquito model.

See the [[STEM Addons | main article]]  for instructions on how to install new features into STEM.

== Updating STEM ==
Starting with version 1.4, you can use the update mechanism built into STEM to perform upgrades without re-downloading the full installation bundle.  Most of the time, this means you don't have to re-download the large denominator data sets packaged in STEM or have to export and import your scenarios.

 PLEASE NOTE. STEM V2.0.x and earlier are based on Eclipse 3.x The Latest versions of STEM beginning with STEM V 3.0.0M1 are base on Eclipse 4.x and therefore require that Java 8 be installed. 
 Please see system requirements above. The following procedure will not update your Java installation. This must be done first.

# Verify the computer is connected to a network and launch '''STEM'''
#: '''If STEM is already open, save all edited files and stop any running simulations'''
# Open the '''Help''' Menu and choose '''Check for Updates'''
#: [[Image:STEM-Update-CheckForUpdatesMenu.png|200px]]
# ''Wait while STEM contacts the updates server and checks for new versions''
#* If no updates are available, a message saying '''No updates were found''' will appear.  Click '''OK''' to return to STEM
#* If an update is available, the '''Available Updates''' wizard will appear
# On the '''Available Updates''' page, verify '''STEM''' is selected, and click '''Next'''
#: [[Image:STEM-Update-AvailableUpdates.png|400px]]
# Verify the list of items to be installed is correct and click '''Next'''
# Review the the licenses of the software being installed to verify you still accept
#: If you accept the terms, select ''' I Accept the terms of the license agreements''' and click '''Finish'''
#: If you do not accept the terms, click '''Cancel'''
# ''Wait while STEM downloads and installs the updates''
# If prompted with a security warning about installing unsigned software, click '''OK'''
# When prompted to apply changes, verify all open files are saved and click '''Restart Now'''
# STEM should automatically restart.  If not, relaunch it manually

=== Checking the Version of STEM Installed ===
After updating STEM, the version displayed on the splash screen at startup may not change to reflect the new version.  To verify STEM updated successfully, check the STEM Installation Details.
# Open the '''Help''' menu and select '''About STEM'''
# Click '''Installation Details'''
# In the '''STEM Installation Details''' dialog, verify the installed version for '''STEM'''
#: [[Image:STEM-Update-InstalledDetailsVersion.png]]

=== Updating to Latest Integration or Milestone Build ===
By default, the STEM update feature only checks for the latest, official release approved by the Eclipse Foundation.  However, users will often want to take advantage of new features published in weekly integration and/or periodic milestone and release candidate builds.  You can easily configure STEM to download and install these updates.

# Launch '''STEM'''
# Open the '''Window''' menu and select '''Preferences'''
#: '' On Mac OS X, '''Preferences''' is under the '''STEM''' menu ''
# In the '''Preferences''' window, expand '''Install/Update''' and select '''Available Software Sites'''
# Under '''Available Software Sites''', click '''Add'''
# In the '''Add Site''' dialog, enter the appropriate '''Name''' and '''Location'''
#: For weekly integration builds:
#:* '''Name''':  STEM Integration Builds
#:* '''Location:''' <nowiki>http://download.eclipse.org/stem/update-site/integration/</nowiki>
#: For periodic milestone and release candidate builds:
#:* '''Name''':  STEM Stable Builds
#:* '''Location:''' <nowiki>http://download.eclipse.org/stem/update-site/stable/</nowiki>
# Click '''OK''' to add the site
# Click '''OK''' to save '''Preferences''' and return to '''STEM'''
# Follow the steps in the [[#Updating_STEM|previous section]] to update '''STEM'''
# ''To disable checking for non-release versions, disable or remove the sites added to the '''Available Software Sites''' list ''

== Setting up the STEM Development Environment in Eclipse ==
If you might contribute to STEM development or if you want to always have the most recent code, then you will need to install Eclipse. 

: '' Go to tutorial on [[STEM Eclipse Setup | Setting up a STEM Development Environment]]