Skip to main content
Jump to: navigation, search

Difference between revisions of "STEM Installation Guide"

(updated required projects)
(Installing Additional STEM Features)
 
(151 intermediate revisions by 8 users not shown)
Line 1: Line 1:
'''[http://wiki.eclipse.org/index.php/STEM STEM Contents Page]'''
+
[[Image:STEM TOP BAR.gif|800px]]
  
=STEM Installation Guide=
 
==Installing  Java™ JVM==
 
STEM requires at least Java Version 1.5.  It also appears to run on Java 1.6.
 
IBMers should obtain the IBM version of Java 1.5.  Others can use either IBM's Java 1.5 or the Sun Java 1.5 [[http://java.sun.com/j2se/1.5.0/download.jsp]].
 
  
For MacOS, you should install Java SE 1.6
+
{| align="left"
 +
  | __TOC__
 +
  |}
  
==Installing the Eclipse Environment==
 
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 [[STEM Eclipse Setup]]
+
<br clear=all>
  
==Obtaining the STEM source code==
+
'''[[STEM|Back to STEM Contents Page]]'''
If you want to obtain the latest version of the STEM source code then you will need to obtain it from the Eclipse CVS repository.
+
  
Goto [[STEM Source Code]]
 
  
==Installing/Running the STEM application==
 
  
 +
== STEM Video on YouTube<sup>TM</sup> ==
 +
The STEM Project published full-length video tutorials for STEM on YouTube in several languages.
  
There are 2 ways to run STEM. One is as a STEM user that has installed Java 1.5 and is running Windows or Linux, and wants to use STEM as a modeling and simulation tool. They would download the STEM application and run it as a standalone application.  
+
#[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]
  
The other way to run STEM is as a STEM developer that has installed
+
== Getting Started ==
Java, the Eclipse development tools and the STEM source code. These users can be running on any platform supported by Eclipse.
+
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:
  
===Running Stem as a standalone application===
+
* 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.
  
If you want to first run STEM as an application then we provide a standalone version of STEM that only requires that you have Java 1.5 or higher installed.
+
=== 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:
  
You can get the file by going to the  
+
# A workstation running an Eclipse-supported operating system:
[http://www.eclipse.org/ohf/components/stem project page]:  
+
#* Windows (XP, Vista, 7)
and then clicking on '''Getting Started'''
+
#* Linux (GTK)
From the '''Getting Started''' page you can download either a zip file for Windows XP/Vista or a gz file for Linux x86.   If you are running on another platform, you will have to download the STEM source code and build STEM for your platform.
+
#* Mac OS X (10.5 or later)
 +
#* A supported Java Standard Edition from either Oracle (Sun) or IBM
 +
#'''For STEM V3.0.0M1 or above the minimum requirement is (J2SE) 8.0 JVM'''
 +
#: [https://java.com/en/download/  Oracle Java SE 8.0 (JRE8U65 or higher)]
 +
# For STEM V 2.0.x or earlier
 +
#: (J2SE) 6.0 JVM
 +
#: [http://www.oracle.com/technetwork/java/javase/downloads/jre6u37-downloads-1859589.html Oracle Java SE 6.0 (6.0.26 or higher)]
 +
#: [http://www.ibm.com/developerworks/java/jdk/ IBM Java SE 6.0]
 +
#* '' '''Note:''' Mac OS X users can use the version included with the operating system ''  
 +
#* '' '''Note:''' The GNU for Java (GCJ) compiler and libraries are not supported. If you're running on Linux, it's strongly recommended you use an Oracle or IBM JRE''
 +
#* '' '''Note:''' While STEM V2.0.x should work with Java 7, it is not tested or supported at this time. STEM V3.0.x is is based on Eclipse 4.x and requires Java 8''
 +
# 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]''
  
Once you have downloaded the zip file, ('''Warning: the download is a very large file and will take awhile to download.''')
+
=== Which File To Download? ===
you would "unzip" the file into your favorite directory.  
+
The STEM Project publishes several different binary versions of the application.  Please consider these options when choosing which to download.
  
This is a self-contained stand-alone version of STEM that is launched by double-clicking on the "STEM.exe" executable file in the root directory of the expanded archive.  You'll need to have Java 1.5 installed for it to run, but if you do and it's on the path,  you should be greeted by the STEM "splash screen" while it starts up.
+
==== 32-bit vs. 64-bit ====
The Eclipse application at this point shows the STEM Simulation Perspective.
+
Most modern operating systems from 2009 and on 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.
<br>
+
STEM Simulation screen.
+
[[Image:Simulation1.jpg|300px]]
+
*The '''Help->Help Context''' menubar selection has extensive information on running STEM.   
+
*The following "views" are shown in the STEM Simulation window.
+
** '''Map''' <br>Canvas that will show the image of the geographic area where the simulation is being run.
+
** '''Simulation Control''' view <br>Panel that both describes the status of the simulation and provides buttons to start and stop the simulation.
+
** '''Scenarios''' <br>The Scenarios window is use to select a prebuilt scenario for a simulation.  By selecting leafs in the tree you can discover an existing scenario for running a simulation.  Select the scenario of choice and click the '''Run''' or '''Advance''' icon on the toolbar. 
+
** '''ErrorLog''' <br>This log will contain information about any errors that occur while running the application.  If things don't work as you expect, check this view to see if there are any errors or exceptions that have occurred. Note that the ErrorLog on the secondary Eclipse will show errors and exceptions that occur in the application being tested but stdout/stderr will be sent to the Console of the Primary Eclipse.  Also if an exception is caught by the application and not passed to the built in log facility it will only show up on the Primary console. Likewise, if an exception is not caught and  sent to stdout/stderr then it will only show up on the secondary ErrorLog.  Confusing!
+
+
  
There are also secondary application that may be selected from the ''Windows'' menu.
+
The STEM project publishes both 32-bit ('''x86''') and 64-bit ('''x86_64''') versions of the application for each supported operating system.  ''' The version you download strictly depends on whether you have a 32-bit or 64-bit Java Runtime Environment (JRE) installed. '''  If you have a 64-bit JRE installed, download the '''x86_64''' version.  Otherwise, download the '''x86''' version.
  
* Select '''windows'''
+
Some 64-bit JREs can run in 32-bit mode.  Please see your JRE's documentation for instructions.
** Select '''GoogleEarth View''' <br> This is an interface between STEM and the GoogleEarth application.  
+
  
The basic idea of the GoogleEarth Interface is to allow the information about the geographic spread of diseases to be reflected on the GoogleEarth Web map. Detailed instructions for using the GoogleEarth Interface are included below.
+
==== Release, Milestone, or Integration Builds ====
[http://wiki.eclipse.org/index.php/Welcome_STEM_Developers#STEM_-_GoogleEarth_Interface]
+
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].
  
===Preparing to Run STEM as a STEM developer===
+
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''.
  
It is possible to run STEM as an application from the Eclipse Development environment without actually creating the standalone Stem application.  
+
== Downloading and Installing STEM ==
Earlier sections described how to set up the environment and checkout the STEM source files.  Once you have done that you will want to run the application using the compiled source. A later section will describe how to build the standalone  Stem application.
+
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:
  
This section will describe how to run and test the STEM application from the source projectsIt assumes that you have downloaded the following projects from  CVS and the build was error free.  
+
<span style="color:#ff0000">'''The STEM installation path cannot contain whitespace charactersEnsure that the install path contains no spaces, tabs, etc.'''</span>
  
* STEM projects (required)
+
''' If you already have STEM 1.4 or newer installed and wish to upgrade, see the [[#STEM_Updates|STEM Updates section]]. '''
** '''org.eclipse.ohf.stem.core'''
+
** '''org.eclipse.ohf.stem.definitions'''
+
** '''org.eclipse.ohf.stem.diseasemodels'''
+
** '''org.eclipse.ohf.stem.diseases'''
+
** '''org.eclipse.ohf.stem.doc'''
+
** '''org.eclipse.ohf.stem.feature'''
+
** '''org.eclipse.ohf.stem.feature.core'''
+
** '''org.eclipse.ohf.stem.feature.prereq'''
+
** '''org.eclipse.ohf.stem.geography'''
+
** '''org.eclipse.ohf.stem.internal.data'''
+
** '''org.eclipse.ohf.stem.jobs'''
+
** '''org.eclipse.ohf.stem.sequencers'''
+
** '''org.eclipse.ohf.stem.ui'''
+
** '''org.eclipse.ohf.stem.ui.diseasemodels'''
+
** '''org.eclipse.ohf.stem.ui.ge'''
+
** '''org.eclipse.ohf.stem.ui.reports'''
+
  
 +
# 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
 +
  
  
* STEM projects (optional)
 
** '''org.eclipse.ohf.stem.jobs.nl1'''
 
** '''org.eclipse.ohf.stem.releng'''
 
** '''org.eclipse.ohf.stem.sample'''
 
** '''org.eclipse.ohf.stem.tests.core'''
 
** '''org.eclipse.ohf.stem.tests.definitions'''
 
** '''org.eclipse.ohf.stem.tests.diseasemodels'''
 
** '''org.eclipse.ohf.stem.tests.jobs'''
 
** '''org.eclipse.ohf.stem.tests.sequencers'''
 
** '''org.eclipse.ohf.stem.tests.ui'''
 
** '''org.eclipse.ohf.stem.ui.nl1'''
 
** '''org.eclipse.ohf.stem.utility'''
 
  
'''Preparing the STEM scenario'''
+
That's it!  STEM is now installed.  See the next section for instructions to launch STEM.
  
The first step is to run a utility that will build the scenarios that you will later use to run the STEM application.
+
== Security Settings in Mac OSx Mojave ==
  
*Select the '''org.eclipse.ohf.stem.internal.data''' project
+
Mojave has new security control features that can make it challenging to install applications and get them to run.
**Select the '''update.xml''' file from the project
+
If you get an error launching STEM follow the instructions below.
**RightClick and select '''run As: ant build...''' (note the ...)
+
**On the '''Modify attributes and launch'' screen:
+
***select '''JRE'''
+
****Specify '''Separate JRE''' (should show some version of JDK 1.5 or later)
+
****For VM arguments: Specify -Xmx512m  (or more)
+
***select '''Properties'''
+
***verify that '''eclipse.contrib''' and '''eclipse.home2''' are defined.  If not, refer to [http://wiki.eclipse.org/index.php?title=STEM_Eclipse_Setup#Installing_Eclipse_Features]
+
***Select '''Run'''
+
  
It will churn away for awhile (maybe 10 minutes or more)  displaying a lot of console output ending with:
+
1. Make sure you dragged the extracted STEM.app to the Applications folder
<code>
+
2. open a console. Enter the following command to temporarily disable Apple Gatekeeper
  BUILD SUCCESSFUL
+
  Total time: n minutes n seconds
+
</code>
+
If you get error messages about eclipse.home2 then refer to [http://wiki.eclipse.org/index.php/STEM_Eclipse_Setup#Installing_Eclipse_Features]
+
  
===Start STEM product===
+
sudo spctl --master-disable
  
Once the scenario is built, you need to startup STEM and run
+
3. Open "System Preferences", click on “Security & Privacy” and check under the General tab.
the simulation.
+
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.
  
* Go to the Package Explorer view
+
6. Open "System Preferences", click on “Security & Privacy” and check under the Privacy tab.
* Select the '''org.eclipse.ohf.stem.ui''' project
+
7. Unlock the settings by clicking on the padlock and entering your password
* Select the appropriate '''.product''' file for your platform.
+
8. UNDER the panel labeled "Allow the apps below to control your computer" click the + button
** Select '''stem.product''' for Windows
+
9. Navigate to STEM.app in the Applications folder and add it to the list.
** Select '''stemLinux.product''' for Linux x86
+
10. Check for the checkbox to Allow
** Select '''stemMacOS.product''' for MacOS
+
11. click on the padlock icon to save the changes
** For other platforms, ??? To be Added ???
+
* From the ''launcher'' tab
+
** specify Program arguments "-consoleLog"
+
** specify VM arguments "-Xmx600M"
+
* From the Overview tab
+
**  select ''Launch'' or ''Launch in Debug mode''.
+
  
It should build a new image of STEM and launch it.
+
== 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]].
  
The system will grind away and start a new instance of Eclipse with support just for STEMIf you have not done this before, you should be aware that this new instance is being controlled by your primary Eclipse instance and console output from your application will be sent back to your primary EclipseAlso you can use the debugger and the debugging controls for the application will be on the primary eclipse window as the application runs in the secondary Eclipse.  
+
# 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 applicationClick '''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 displayYou 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]] ''
  
You are now running the STEM application.  See the instructions for running the Standalone version of STEM
+
== Configure STEM Preference ==
[http://wiki.eclipse.org/index.php/Installation_Guide#Running_Stem_as_a_standalone_application]
+
  
Also, use the '''Help->Help Context''' from the menubar to get extensive '''Help''' information.
+
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.
  
===Generate JavaDoc for STEM===
 
You can easily generate JavaDoc for STEM with the following process.
 
*Select the '''org.eclipse.ohf.stem.doc''' project
 
**Select the '''javadoc.xml''' file from the project
 
**RightClick and select '''run As: ant build'''
 
  
This will generate javadoc in '''org.eclipse.ohf.stem.doc/javadoc''' and
+
==Installing Additional STEM Features==
it can be displayed by selecting the '''index.html''' member.
+
: '' See section on [[STEM Addons | STEM Add-ons]] ''
  
===Understanding '''stem.product'''===
+
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
The file '''stem.product''' in '''org.eclipse.ohf.stem.ui''' is a very important piece of the process to launch an application. 
+
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.
However it appears to be a trial and error process to
+
generate the list of  plugins.  
+
  
 +
See the [[STEM Addons | main article]]  for instructions on how to install new features into STEM.
  
Also it is important to note that there seems to be a difference between launching STEM from "Run" on the eclipse menubar and from the "launch" or "Debug" buttons on the "Overview" tab from the '''org.eclipse.ogh.stem.ui''' '''stem.product''' selection.
+
== 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 bundleMost 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.
  
If you update the list of plugins in the "Configuration" tap for stem.product that does
+
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.
not update the list of plugins that are used when you select a launch entry from the menubar.   However, using the launch entry from stem.product overview appears to then update the menubar launch.   Very confusing!!!
+
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'''
The following section is to give some info about the reason for
+
#: '''If STEM is already open, save all edited files and stop any running simulations'''
including each of the plugins.  There are lots of ? because
+
# Open the '''Help''' Menu and choose '''Check for Updates'''
short of trying it without the plugin there is no way to
+
#: [[Image:STEM-Update-CheckForUpdatesMenu.png|200px]]
be sure.
+
# ''Wait while STEM contacts the updates server and checks for new versions''
Col 1 has the following codes
+
#* If no updates are available, a message saying '''No updates were found''' will appearClick '''OK''' to return to STEM
R  Required for base system
+
#* If an update is available, the '''Available Updates''' wizard will appear
R? probably required for base
+
# On the '''Available Updates''' page, verify '''STEM''' is selected, and click '''Next'''
B  BIRT
+
#: [[Image:STEM-Update-AvailableUpdates.png|400px]]
H  Help
+
# Verify the list of items to be installed is correct and click '''Next'''
W  Webserver
+
# Review the the licenses of the software being installed to verify you still accept
O  OHF STEM required projects for RCP
+
#: If you accept the terms, select ''' I Accept the terms of the license agreements''' and click '''Finish'''
- Platform specific
+
#: If you do not accept the terms, click '''Cancel'''
?  unknown but appears to be required
+
# ''Wait while STEM downloads and installs the updates''
?? unknown and not tried to run without.
+
# 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'''
?    <plugin id="com.ibm.icu"/>
+
# STEM should automatically restartIf not, relaunch it manually
B?    <plugin id="com.lowagie.itext"/>    ** only for specific functions
+
 
H    <plugin id="javax.servlet"/>
+
=== Checking the Version of STEM Installed ===
  H?    <plugin id="javax.servlet.jsp"/>
+
After updating STEM, the version displayed on the splash screen at startup may not change to reflect the new versionTo verify STEM updated successfully, check the STEM Installation Details.
R?    <plugin id="org.apache.ant"/>
+
# Open the '''Help''' menu and select '''About STEM'''
??    <plugin id="org.apache.batik.pdf"/>
+
# Click '''Installation Details'''
??    <plugin id="org.apache.commons.codec"/>
+
# In the '''STEM Installation Details''' dialog, verify the installed version for '''STEM'''
??    <plugin id="org.apache.commons.el"/>
+
#: [[Image:STEM-Update-InstalledDetailsVersion.png]]
??    <plugin id="org.apache.commons.logging"/>
+
 
H?    <plugin id="org.apache.jasper"/>
+
=== Updating to Latest Integration or Milestone Build ===
H    <plugin id="org.apache.lucene"/>
+
By default, the STEM update feature only checks for the latest, official release approved by the Eclipse FoundationHowever, users will often want to take advantage of new features published in weekly integration and/or periodic milestone and release candidate buildsYou can easily configure STEM to download and install these updates.
H?    <plugin id="org.apache.lucene.analysis"/>
+
??    <plugin id="org.apache.xerces"/>
+
??    <plugin id="org.apache.xml.resolver"/>
+
??    <plugin id="org.eclipse.ant.core"/>
+
  B    <plugin id="org.eclipse.birt.chart.device.extension"/>
+
B    <plugin id="org.eclipse.birt.chart.device.svg"/>
+
B    <plugin id="org.eclipse.birt.chart.device.swt"/>
+
B    <plugin id="org.eclipse.birt.chart.engine"/>
+
B    <plugin id="org.eclipse.birt.chart.engine.extension"/>
+
B    <plugin id="org.eclipse.birt.chart.ui"/>
+
B    <plugin id="org.eclipse.birt.chart.ui.extension"/>
+
B    <plugin id="org.eclipse.birt.core"/>
+
B    <plugin id="org.eclipse.birt.core.ui"/>
+
R?    <plugin id="org.eclipse.core.commands"/>
+
R?    <plugin id="org.eclipse.core.contenttype"/>
+
R?    <plugin id="org.eclipse.core.databinding"/>
+
R?    <plugin id="org.eclipse.core.expressions"/>
+
?    <plugin id="org.eclipse.core.filesystem"/>
+
-    <plugin id="org.eclipse.core.filesystem.win32.x86" fragment="true"/>
+
R?    <plugin id="org.eclipse.core.jobs"/>
+
R    <plugin id="org.eclipse.core.net"/>
+
R?    <plugin id="org.eclipse.core.resources"/>
+
R?    <plugin id="org.eclipse.core.resources.compatibility" fragment="true"/>
+
R?    <plugin id="org.eclipse.core.resources.win32" fragment="true"/>
+
R?    <plugin id="org.eclipse.core.runtime"/>
+
R?    <plugin id="org.eclipse.core.runtime.compatibility.auth"/>
+
R?    <plugin id="org.eclipse.core.runtime.compatibility.registry" fragment="true"/>
+
R?    <plugin id="org.eclipse.core.variables"/>
+
R?    <plugin id="org.eclipse.emf.common"/>
+
R?    <plugin id="org.eclipse.emf.common.ui"/>
+
R?    <plugin id="org.eclipse.emf.ecore"/>
+
R?    <plugin id="org.eclipse.emf.ecore.change"/>
+
R?    <plugin id="org.eclipse.emf.ecore.xmi"/>
+
  R?    <plugin id="org.eclipse.emf.edit"/>
+
R?    <plugin id="org.eclipse.emf.edit.ui"/>
+
R?    <plugin id="org.eclipse.equinox.app"/>
+
R?    <plugin id="org.eclipse.equinox.common"/>
+
H    <plugin id="org.eclipse.equinox.http.jetty"/>
+
H    <plugin id="org.eclipse.equinox.http.registry"/>
+
H    <plugin id="org.eclipse.equinox.http.servlet"/>
+
H    <plugin id="org.eclipse.equinox.jsp.jasper"/>
+
H    <plugin id="org.eclipse.equinox.jsp.jasper.registry"/>
+
?    <plugin id="org.eclipse.equinox.preferences"/>
+
?    <plugin id="org.eclipse.equinox.registry"/>
+
H    <plugin id="org.eclipse.help"/>
+
H    <plugin id="org.eclipse.help.appserver"/>
+
H    <plugin id="org.eclipse.help.base"/>
+
H    <plugin id="org.eclipse.help.ui"/>
+
H    <plugin id="org.eclipse.help.webapp"/>
+
?    <plugin id="org.eclipse.jdt.core"/>
+
?    <plugin id="org.eclipse.jface"/>
+
?    <plugin id="org.eclipse.jface.databinding"/>
+
?    <plugin id="org.eclipse.jface.text"/>
+
O    <plugin id="org.eclipse.ohf.stem.core"/>
+
O    <plugin id="org.eclipse.ohf.stem.definitions"/>
+
O    <plugin id="org.eclipse.ohf.stem.diseasemodels"/>
+
O    <plugin id="org.eclipse.ohf.stem.diseases"/>
+
O    <plugin id="org.eclipse.ohf.stem.geography"/>
+
O    <plugin id="org.eclipse.ohf.stem.jobs"/>
+
O    <plugin id="org.eclipse.ohf.stem.jobs.nl1" fragment="true"/>
+
O    <plugin id="org.eclipse.ohf.stem.sequencers"/>
+
O    <plugin id="org.eclipse.ohf.stem.ui"/>
+
O    <plugin id="org.eclipse.ohf.stem.ui.diseasemodels"/>
+
O    <plugin id="org.eclipse.ohf.stem.ui.ge"/>
+
O    <plugin id="org.eclipse.ohf.stem.ui.nl1" fragment="true"/>
+
O    <plugin id="org.eclipse.ohf.stem.ui.reports"/>
+
R?    <plugin id="org.eclipse.osgi"/>
+
R?    <plugin id="org.eclipse.osgi.services"/>
+
R?    <plugin id="org.eclipse.osgi.util"/>
+
R?    <plugin id="org.eclipse.pde.runtime"/>
+
R?    <plugin id="org.eclipse.swt"/>
+
-     <plugin id="org.eclipse.swt.win32.win32.x86" fragment="true"/>
+
??    <plugin id="org.eclipse.team.core"/>
+
?    <plugin id="org.eclipse.text"/>
+
W    <plugin id="org.eclipse.tomcat"/>
+
R?    <plugin id="org.eclipse.ui"/>
+
R?    <plugin id="org.eclipse.ui.forms"/>
+
R?    <plugin id="org.eclipse.ui.ide"/>
+
R?    <plugin id="org.eclipse.ui.views"/>
+
-    <plugin id="org.eclipse.ui.win32" fragment="true"/>
+
R?    <plugin id="org.eclipse.ui.workbench"/>
+
?    <plugin id="org.eclipse.update.configurator"/>
+
  ?    <plugin id="org.eclipse.update.core"/>
+
?    <plugin id="org.eclipse.update.core.win32" fragment="true"/>
+
  ?    <plugin id="org.eclipse.update.ui"/>
+
??    <plugin id="org.eclipse.xsd"/>
+
??    <plugin id="org.junit"/>
+
H    <plugin id="org.mortbay.jetty"/>
+
B    <plugin id="org.mozilla.rhino"/>
+
??    <plugin id="org.w3c.dom"/>
+
  
 +
# 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 ''
  
The following plugins get added to stem.product by
+
== Setting up the STEM Development Environment in Eclipse ==
the "add required plugins" but they should be deleted
+
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.  
because they are not needed and caused error messages at
+
startup. They appear to require Java 6
+
  
org.eclipse.jdt.compiler.apt
+
: '' Go to tutorial on [[STEM Eclipse Setup | Setting up a STEM Development Environment]]
org.eclipse.jdt.internal.compiler.tool
+

Latest revision as of 13:01, 22 July 2019

STEM TOP BAR.gif




Back to STEM Contents Page


STEM Video on YouTubeTM

The STEM Project published full-length video tutorials for STEM on YouTube in several languages.

  1. STEM Model Generator (new!!) requires STEM V2.0 milestone
  2. Full length video In English
  3. Full length video In Hebrew
  4. Full length video In Japanese
  5. Full length video In Spanish
  6. 5 min Video (English)
  7. Avian Influenza
    1. Only Poultry-Human Transmission
    2. Including 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 Setting up a STEM Development Environment page for more instructions.

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:

  1. A workstation running an Eclipse-supported operating system:
    • Windows (XP, Vista, 7)
    • Linux (GTK)
    • Mac OS X (10.5 or later)
    • A supported Java Standard Edition from either Oracle (Sun) or IBM
  2. For STEM V3.0.0M1 or above the minimum requirement is (J2SE) 8.0 JVM
    Oracle Java SE 8.0 (JRE8U65 or higher)
  3. For STEM V 2.0.x or earlier
    (J2SE) 6.0 JVM
    Oracle Java SE 6.0 (6.0.26 or higher)
    IBM Java SE 6.0
    • Note: Mac OS X users can use the version included with the operating system
    • Note: The GNU for Java (GCJ) compiler and libraries are not supported. If you're running on Linux, it's strongly recommended you use an Oracle or IBM JRE
    • Note: While STEM V2.0.x should work with Java 7, it is not tested or supported at this time. STEM V3.0.x is is based on Eclipse 4.x and requires Java 8
  4. A tool to extract zipped archives
    Most operating systems have this built-in, although Windows users may wish to install a standalone utility like 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

Most modern operating systems from 2009 and on 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 STEM project publishes both 32-bit (x86) and 64-bit (x86_64) versions of the application for each supported operating system. The version you download strictly depends on whether you have a 32-bit or 64-bit Java Runtime Environment (JRE) installed. If you have a 64-bit JRE installed, download the x86_64 version. Otherwise, download the x86 version.

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 Eclipse Software User Agreement and the 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:

The STEM installation path cannot contain whitespace characters.  Ensure that the install path contains no spaces, tabs, etc.

If you already have STEM 1.4 or newer installed and wish to upgrade, see the STEM Updates section.

  1. In your browser, go to the STEM Downloads page
  2. Choose the appropriate bundle to download (see previous section for help) and click the link
  3. On the mirrors page, select a nearby mirror site. This will begin the download.
  4. 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.
  5. 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.
  6. When the download finishes, open the folder where the downloaded file sits
  7. Extract/unzip the STEM archive
    Note: On most systems, double clicking the the .zip file will automatically extract it.
  8. 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
  9. Optionally, you can create a shortcut on your desktop, start menu, dock, etc to quickly launch STEM
  10. 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).
    1. 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
    2. 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)
    1. Right click on the STEM.app icon
    2. select Show Package Contents
    3. navigate to >Contents>Eclipse
    4. Open the STEM.ini file
    5. 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:
      1. -Xms512m
      2. -Xmx4096m
      3. -XX:PermSize=256m
      4. -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 headless STEM article.

  1. Navigate to the folder STEM is installed in
  2. Double click the STEM executable file
    STEM-Install-FinderView.png
    • 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
  3. 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
    STEM-Install-DownloadedApplicationWarning.png
  4. The STEM splash screen should immediately appear
    STEM-Install-Splash.png
  5. 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.
  6. 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.
    STEM-Install-WelcomeScreen.png
  7. Congratulations! STEM is loaded and ready to use
    STEM-Install-Workbench.png
  8. To get started using STEM, start by going through the tutorials on the STEM Documentation page
    You may find it helpful to watch the YouTube tutorial before you go on to learn to create a scenario

Configure STEM Preference

Next you should configure STEM runtime preferences. After launch, on the menu bar,

  1. 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
  2. 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.
  3. 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.
  4. Look at the other STEM configuration settings. You can customize a number of features.


Installing Additional STEM Features

See section on 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 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.
  1. 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
  2. Open the Help Menu and choose Check for Updates
    STEM-Update-CheckForUpdatesMenu.png
  3. 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
  4. On the Available Updates page, verify STEM is selected, and click Next
    STEM-Update-AvailableUpdates.png
  5. Verify the list of items to be installed is correct and click Next
  6. 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
  7. Wait while STEM downloads and installs the updates
  8. If prompted with a security warning about installing unsigned software, click OK
  9. When prompted to apply changes, verify all open files are saved and click Restart Now
  10. 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.

  1. Open the Help menu and select About STEM
  2. Click Installation Details
  3. In the STEM Installation Details dialog, verify the installed version for STEM
    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.

  1. Launch STEM
  2. Open the Window menu and select Preferences
    On Mac OS X, Preferences is under the STEM menu
  3. In the Preferences window, expand Install/Update and select Available Software Sites
  4. Under Available Software Sites, click Add
  5. In the Add Site dialog, enter the appropriate Name and Location
    For weekly integration builds:
    • Name: STEM Integration Builds
    • Location: http://download.eclipse.org/stem/update-site/integration/
    For periodic milestone and release candidate builds:
    • Name: STEM Stable Builds
    • Location: http://download.eclipse.org/stem/update-site/stable/
  6. Click OK to add the site
  7. Click OK to save Preferences and return to STEM
  8. Follow the steps in the previous section to update STEM
  9. 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 Setting up a STEM Development Environment

Back to the top