View source for STEM Headless

STEM Headless mode enables the running of STEM simulations without the use of the STEM Workbench / Graphical User Interface.  Headless mode can be useful in environments where no window manager is available, such as remote, text-only server consoles.

Headless mode can be launched from the STEM binary distributed with the STEM distribution.  Simply supply the '''-headless''' command line argument.

== Headless STEM Command Line Options ==

* <code style="font-size: 10pt;">stem -nosplash -headless -loadWorkspacePlugins [-quiet] [-log [LOG_DIRECTORY]] [-uri URI1 [...]] [-project PROJECT_NAME [-scenario SCENARIO1.scenario [...]]]</code>

==='''Command Descriptions'''===

'''-nosplash'''
: Tells the Eclipse Framework to ''not'' show the splash screen.  This prevents certain UI libraries from getting loaded.

'''-headless'''
: Tells the STEM Launcher to use the headless mode, e.g. not to launch the GUI workbench.

'''-quiet'''
: ''Optional'' STEM headless will run in quiet mode.  Nothing will be written to ''standard out'' (stdout).  Errors and exceptions may still be sent to ''standard error'' (stderr).

'''-loadWorkspacePlugins'''
: ''Experimental, Optional'' Load plug-ins created with the model generator that reside in the workspace

'''-log [LOG_DIRECTORY]'''
:  ''Optional'' attachs a comma-separated value (CSV) logger to all simulations.  Optional additional value ''LOG_DIRECTORY'' represents the path to the parent directory for logs.  If LOG_DIRECTORY is not set, logs will go to the default log directory for the simulation (''PROJECT_NAME/Recorded Simulations'' folder).
 Please Note: There is a defect when logging compartments generated by the model builder. 
 For the workaround please see the page [[Server Side Logger Workaround]]

'''-uri URI1 [...]'''
:  ''Optional'' A list of one or more STEM resource URIs pointing to scenarios to launch and simulate.
:  ''Optional'' URI1 can be either a scenario of an automatic experiment (both can now be run headless).

'''-project PROJECT_NAME'''
: ''Optional'' Creates and runs simulations for scenarios in the STEM project ''PROJECT_NAME''.  If no '''-scenario''' parameter is specified, all scenarios in the given project will be run.

'''-scenario SCENARIO1.scenario [...]'''
: ''Optional, dependent on -project''.  A list of one or more scenario files contained in the given '''-project''''s ''Scenarios'' folder to launch and run.  If no '''-scenario''' is defined, all scenarios in the given project will be run.

=== Usage Examples ===
The following are a list of example command invocations for the STEM headless mode.  The STEM UI will not launch in any of these examples.  The examples make use of the UsaMexico project, which can be downloaded [http://www.eclipse.org/stem/download_sample.php?file=UsaMexicoDemo.zip from here].

* <code style="font-size: 10pt;">stem -headless</code>
*: Launches STEM headless mode, but does nothing else and immediately exits

* <code style="font-size: 10pt;">stem -headless -uri platform:/resource/UsaMexico/scenarios/UsaMexicoScenarioLevel2.scenario</code>
*: Runs a simulation for the scenario at the given URI, printing simulation status to the console.

* <code style="font-size: 10pt;">stem -headless -project UsaMexico</code>
*: Runs simulations for all scenarios in the ''UsaMexico'' project, printing simulation status to the console.

* <code style="font-size: 10pt;">stem -headless -project UsaMexico -scenario UsaMexicoScenarioLevel2.scenario UsaMexicoScenarioNoPolicy.scenario</code>
*: Runs simulations for the scenarios ''UsaMexicoScenarioLevel2'' and ''UsaMexicoScenarioNoPolicy'' in the project ''UsaMexico'', printing simulation status to the console.

* <code style="font-size: 10pt;">stem -headless -quiet -uri platform:/resource/UsaMexico/scenarios/UsaMexicoScenarioLevel2.scenario</code>
*: Runs a simulation for the given URI in quiet mode, printing only errors to the console.

* <code style="font-size: 10pt;">stem -headless -uri platform:/resource/YOUR_PROJECT/experiments/YOUR_AUTOMATED_EXPERIMENT.automaticexperiment</code> 
*: Runs a simulation for the scenario at the given URI, printing simulation status to the console.

* <code style="font-size: 10pt;">stem -headless -log -uri platform:/resource/UsaMexico/scenarios/UsaMexicoScenarioLevel2.scenario</code>
*: Runs a simulation for the given URI and logs the simulation output in CSV format to the default log directory.

* <code style="font-size: 10pt;">stem -headless -log /var/log -uri platform:/resource/UsaMexico/scenarios/UsaMexicoScenarioLevel2.scenario</code>
*: Runs a simulation for the given URI and logs the simulation output in CSV format to the ''/var/log'' folder.

== Using ssh to launch STEM remotely ==

=== ssh -XY <server> ===

On some systems launching the equinox application, even headless, will crash on startup without a graphics emulator. To avoid this problem when using ssh to connect to a remote server (for example) be sure to use the -XV flags when ssh'ing to the server. Please note both 'X' and 'Y' are upper case. 

 ssh -XY <server>
 -X      Enables X11 forwarding.  This can also be specified on a per-host basis in a configuration file
 -Y      Enables trusted X11 forwarding.  Trusted X11 forwardings are not subjected to the X11 SECURITY extension controls.

 Please see ssh documentation[http://linuxcommand.org/man_pages/ssh1.html] for more details. 

=== X11 emulation ===

You may also have to install an X11 emulator to get everything to work. See, for example, XQuartz would be the answer there:  http://www.xquartz.org/[http://www.xquartz.org/]