Commit 8d953a9e authored by Robert Smith's avatar Robert Smith
Browse files

Merge branch 'next' of https://github.com/eclipse/ice into next

parents aad457d0 ece712e8
/main.aux
/main.log
/main.out
/main.aux
/main.log
/main.out
/main.pdf
\section{Installation}
You have been provided a USB stick with all you will need for this tutorial. On
this drive is the following: ICE binaries for your OS, a clone of the ICE git
repository, all tutorial documentation and slides for today, and
data files for the tutorial.
this drive is the following:
\begin{itemize}
\item An ICE application for your operating system
\item A clone of the ICE git repository
\item All tutorial documentation and slides for today
\item Data files for the tutorial.
\end{itemize}
\section*{ICE Installation}
A number of files must first be copied from the
USB stick to your local machine:
\subsection{ICE Installation}
A number of files must first be copied from the USB stick to your local machine. Please
follow the steps below:
\begin{enumerate}
\item Choose a location that is easy to remember
and copy the correct \texttt{ice\-product*.zip} file for your computer's
operation system (Linux, Mac OS X, or Windows).
\item Unzip this file to obtain the
ICE application executable.
\item Copy the git repository \texttt{repository.zip} file to your computer.
\item Copy the git repository \texttt{ice-repository.zip} file to your computer.
\item Unzip this file.
\end{enumerate}
\section*{Starting ICE}
\subsection{Starting ICE for the first time}
To start ICE, double-click on the application executable to open up ICE. When the workspace chooser
dialog opens, select the default workspace.
dialog opens, select the default workspace by clicking on the \texttt{OK}
button.
You can enter your own directory for the workspace location, but please make sure that it is writable and readable by you, and you remember where it is.
\begin{center} \includegraphics[width=\textwidth]{figures/workspace}
\end{center}
When ICE opens you should see something similar to the below image.
When ICE opens you should see an empty \texttt{Plug-in Development} perspective
similar to the image below.
\begin{center} \includegraphics[width=\textwidth]{figures/expectedICE}
\end{center}
\section*{Setting up ICE}
In order to develop an application dashboard, a development version of ICE
must be setup. The first step in doing this is to load the ICE bundles into
\subsection{Setting up ICE}
In order to create a dashboard for your application, you will need to configure ICE to
be able to develop ICE. This \textit{Software Development Kit (SDK) version} of
ICE will contain all the components necessary to generate a new instance of ICE that will become your application's dashboard.
The first step in doing this is to load the ICE bundles into
your workspace. We have provided a developer menu to assist in this process:
\begin{enumerate}
\item Select \texttt{Developer $\rightarrow$ ICE $\rightarrow$
Import from local repository}
Import Local Repository}
\item Using the directory dialog, navigate to the git repository you copied
from the USB drive.
\item Select \texttt{Open}
\item In the \texttt{Search results} list, select the checkbox next to the
repository
\item Select \texttt{Finish}
\end{enumerate}
This should import all the ICE bundles and you should have something
like the image below.
like the image below. \textit{Note: you may see errors on some of the projects,
these can safely be ignored.}
\begin{center} \includegraphics[width=\textwidth]{figures/cloned} \end{center}
At this point, you are ready to begin developing a dashboard for your
application!
\section*{Overview}
\section{Overview}
This tutorial will teach you how you
can create your own ICE Items via the built in tools within ICE. To demonstrate
This tutorial will teach you how to
create your own ICE Items via the built in tools within ICE. To demonstrate
these tools, we will walk through the development of an ICE Item project for the
FERN code, a fast efficient nuclear reaction network solver.
So we don't have to worry about building Fern for this tutorial, we have
provided a convenient Docker image for Fern that you may use.
This image must be a part of your local docker daemon images list for use in
this tutorial. You can add the image to your local Docker daemon in 2 ways: build the
image with the provided Dockerfile, or load the image through the image tar ball we have provided. To
build it from scratch, in the same directory as the Dockerfile, run
\begin{lstlisting}[language=bash,caption={bash version}]
docker build -t eclipseice/fern .
\end{lstlisting}
To load the image from the provided tar ball, run
\begin{lstlisting}[language=bash,caption={bash version}]
docker load < fernImage.tar.gz
\end{lstlisting}
FERN code, a fast, efficient nuclear reaction network solver.
After creating a new ICE Item plugin project, we will demonstrate how to
provide a few lines of code to get a Model Item showing in ICE that creates
input files for FERN. After that we will add a little code to the FERN
JobLauncher to be able to execute FERN locally, remotely, or via the
provided Docker image.
provided Docker image. Before we begin, ensure that you have ICE cloned
(Developer $>$ ICE $>$ Clone ICE or Developer $>$ ICE $>$ Import Local
Repository) into your workspace.
Before we begin, make sure you have ICE cloned (Developer $>$ ICE $>$ Clone ICE)
into your workspace, and the provided Docker image loaded to your local Docker daemon.
\section*{Creating a New ICE Item Plugin Project}
\section{Creating the Project}
\begin{figure}[h]
\centering
......@@ -46,18 +32,14 @@ Now you are able to customize the plugin-specific portions of the project. We do
not need an Activator to be generated, so uncheck that box, then select
\texttt{Next}.
On this page you simply need to tell the wizard what you want to use as a base
name for your item classes. We will call this one \texttt{Fern}. Then, we will
On this page you need to tell the wizard what you want to use as a base
name for your item classes. We will call this one \texttt{Fern}. Then, we will
specify some information about how the item will handle input data. Fern uses
the INI file format to specify data, so we will tell our item to use the built-in
functionality for INI files. To do this select \texttt{INI} from the \texttt{File Format} dropdown.
Next we will provide a default data set to load when an item is created. This step
makes the item generation process much quicker by reducing the amount of code we need to write.
Click the \texttt{Browse} button and select the \texttt{alpha.ini} file from the data provided
in the tutorial files.
functionality for INI files. To do this select \texttt{INI} from the \texttt{File Format} dropdown.
When you have entered all of the required information you can
click the \texttt{Finish} button to generate your new ICE Item plugin project.
When the project has finished generating you should be able to explore the code
that has been created. Within the source directory there will be two packages,
each containing two Java classes:
......@@ -75,32 +57,198 @@ each containing two Java classes:
\end{itemize}
\end{itemize}
To add functionality to the project you will only be responsible for editing
the \texttt{Launcher} and \texttt{Model} classes and can ignore the
\texttt{LauncherBuilder} and \texttt{ModelBuilder} classes.
To add functionality to the project we need to edit
the \texttt{FernLauncher} and \texttt{FernModel} classes.
\section{Adding Functionality to the New Items}
\section*{Adding Functionality to the New Items}
\subsection*{The Fern Model}
\subsection{The Fern Model}
The \texttt{FernModel} will be responsible for creating and
validating input parameters for FERN, in the form of a new FERN input file.
The Fern Model is largely completed, thanks to the additional information about
the file format and initial data that we provided during the creation of the
project.
validating input parameters for FERN, in the form of a new FERN input file. In
order to make the generated code run there are several pieces of information that need to be changed. First, we
will need to set up the basic Item idenfification information. This information
is set in the setupItemInfo() method. Modify the outputName to match the
following (or something of your choosing, with a .ini file extenstion).
\begin{lstlisting}[language=Java]
outputName = "fern_config.ini";
\end{lstlisting}
The String for the \emph{setName} method will serve as the display name
for this Item, so set it as \texttt{Fern Model}.
As for the String for \emph{setDescription}, this will also be used on the UI
for the Item, so provide some text like the following: \texttt{This Item constructs input files
for the FERN reaction network solver}. The export string will serve as the name
of the action that the user can select to write the provided data to file. Set
it to something like: \texttt{Export to INI}. You should now have a method that
looks like this:
\begin{lstlisting}[language=Java]
@Override
protected void setupItemInfo() {
setName("Fern Model");
setDescription("This Item constructs " +
"input files for the FERN reaction " +
"network solver");
outputName = "fern_output.ini";
exportString = "Export to INI";
allowedActions.add(0, exportString);
ioFormat = "INI";
defaultFileName = "";
}
\end{lstlisting}
The \emph{allowedActions.add()} line ensures that the export string is provided
to ICE as an allowed action, and displayed in the Item Process drop down.
With the identification information configured properly we can begin to
implement the Form for this Fern Model. This is done in the \emph{setupForm()}
method.
The generator has begun the process of implementing this method by instantiating
a Form for you to use, getting a reference to the IOService (which provides
IReader/IWriter realizations), and providing a commented out example of how to
fill out an ICE Form.
For this FERN input model, we want to add the following sections with data
entries: a network section with
numSpecies, numReactions, numReactionGroups, massTol, fluxFrac, networkFile,
rateFile data entries, an initialConditions section with T9, startTime, endTime,
initialTimeStep, and density, and an output section with a single popFile
data entry.
To achieve this for this Item, we will need to add three
\texttt{DataComponents}, one for the network section, another for the
initialConditions section, and a final one for the outputs section. To each of
those DataComponents we will add appropriate IEntry instances for each of the data entries we have.
If you are interested in other ways that you can customize the model item you
can open the \texttt{FernModel.java} and browse through the source code. There
are comments that provide examples of other ways that the item can be set up
and used.
Add the following to your setupForm() method:
\subsection*{Fern Launcher}
\begin{lstlisting}[language=Java]
// Create the network section
DataComponent networkComp = new DataComponent();
networkComp.setName("network");
networkComp.setDescription("The parameters needed " +
"to describe the nuclear " +
"reaction network");
networkComp.setId(1);
// Create the IEntries we need for this DataComponent
StringEntry numSpecies = new StringEntry();
numSpecies.setName("numSpecies");
numSpecies.setDescription("The number of species to consider");
numSpecies.setDefaultValue("16");
StringEntry numReactions = new StringEntry();
numReactions.setName("numReactions");
numReactions.setDescription("The number of reactions to consider");
numReactions.setDefaultValue("48");
StringEntry numReactionGrps = new StringEntry();
numReactionGrps.setName("numReactionsGroups");
numReactionGrps.setDescription("The number of reaction " +
"groups to consider");
numReactionGrps.setDefaultValue("19");
StringEntry massTol = new StringEntry();
massTol.setName("massTol");
massTol.setDescription("The mass tolerance to consider");
massTol.setDefaultValue("1e-7");
StringEntry fluxFrac = new StringEntry();
fluxFrac.setName("fluxFrac");
fluxFrac.setDescription("The flux fraction to consider");
fluxFrac.setDefaultValue(".01");
FileEntry networkFile = new FileEntry(".inp");
networkFile.setProject(project);
networkFile.setName("networkFile");
networkFile.setDescription("The network file for this problem");
FileEntry rateFile = new FileEntry(".data");
rateFile.setProject(project);
rateFile.setName("rateFile");
rateFile.setDescription("The rate file for this problem");
networkComp.addEntry(numSpecies);
networkComp.addEntry(numReactions);
networkComp.addEntry(numReactionGrps);
networkComp.addEntry(massTol);
networkComp.addEntry(fluxFrac);
networkComp.addEntry(networkFile);
networkComp.addEntry(rateFile);
// Create the initial conditions section
DataComponent initConditionsComp = new DataComponent();
initConditionsComp.setName("initialConditions");
initConditionsComp.setId(2);
initConditionsComp.setDescription("The parameters " +
"needed to describe the initial " +
"conditions for the problem");
StringEntry t9 = new StringEntry();
t9.setName("T9");
t9.setDescription("The temperature in Kelvin x 10^9");
t9.setDefaultValue("7.0");
StringEntry startTime = new StringEntry();
startTime.setName("startTime");
startTime.setDescription("The start time for the simulation.");
startTime.setDefaultValue("1e-20");
StringEntry endTime = new StringEntry();
endTime.setName("endTime");
endTime.setDescription("The end time for the simulation");
endTime.setDefaultValue("1e-3");
StringEntry initialTimeStep = new StringEntry();
initialTimeStep.setName("initialTimeStep");
initialTimeStep.setDescription("The initial time step " +
"for the simulation.");
initialTimeStep.setDefaultValue("1.2345e-22");
StringEntry density = new StringEntry();
density.setName("density");
density.setDescription("The initial density.");
density.setDefaultValue("1e8");
initConditionsComp.addEntry(t9);
initConditionsComp.addEntry(startTime);
initConditionsComp.addEntry(endTime);
initConditionsComp.addEntry(initialTimeStep);
initConditionsComp.addEntry(density);
// Create the outputs section
DataComponent outputComp = new DataComponent();
outputComp.setName("output");
outputComp.setDescription("The parameters needed to output data.");
outputComp.setId(3);
StringEntry popFile = new StringEntry();
popFile.setName("popFile");
popFile.setDescription("The name of the output populations file");
popFile.setDefaultValue("popFile.csv");
outputComp.addEntry(popFile);
// Add the components to the Form
form.addComponent(networkComp);
form.addComponent(initConditionsComp);
form.addComponent(outputComp);
\end{lstlisting}
Now we have a Form constructed for a typical FERN execution.
The default generated implementation of the process method is sufficient to be
able to create new Fern INI input files.
\subsection{Fern Launcher}
The Fern Launcher handles the actual execution of the FERN application. The
generator creates the FernLauncher as a subclass of ICE's JobLauncher, which
provides a large array of features and functionality. As a subclass of
JobLauncher, the FernLauncher enables users to execute Fern locally, remotely,
or even through a Docker image. To do so, we just need to add a small amount of
JobLauncher, the FernLauncher enables users to execute Fern locally or remotely.
To do so, we just need to add a small amount of
code that customizes the ICE job launching capabilities for Fern.
The first bit of code to add to the FernLauncher specifies the name of the
......@@ -111,15 +259,11 @@ execCommand = "${installDir}fern-exec";
\end{lstlisting}
This tells ICE that the Fern executable is called \texttt{fern-exec}, and to
set the overall execution command to it's install path plus the executable name.
The installDir flag will tell ICE to insert the user-specified executable
location (provided through the graphical form editor') into the execCommand,
with a trailing OS-specific path separator. This install directory is
specified through the Hosts Table on the editory.
As for the Hosts information in the setupForm() method, let's simply change the
install path to what we know it will be in the Docker container we will use -
\texttt{/usr/bin}.
You can actually just change this on the Fern Launcher UI, but for efficiency, let's
do it here.
\begin{lstlisting}[language=Java]
addHost("localhost", "linux x86_64", "/usr/bin");
\end{lstlisting}
We also need to inform the JobLauncher what other files are involved in this
execution. To do that, the JobLauncher provides an addInputType() method. Add
the following to setupForm():
......@@ -135,12 +279,14 @@ The generator has taken care of everything else for us.
We are now ready to launch ICE with our Fern plugin, and use the Fern Items we
have just created.
\section*{Using the New Fern Items}
Now, using these new Items is easy. Open the Run Configurations wizard with
\texttt{Run $>$ Run Configurations\ldots}, and open Eclipse Applications to see ICE
launch configurations for Mac, Linux, and Windows. Select the launch configuration for your OS and open the Plug-ins
tab. Scroll down to the \texttt{org.eclipse.ice.fern} plugin and turn it on for
this launch configuration by clicking the check box. Then click Apply and Run.
\section{Using the New Fern Items}
Now, using these new Items is easy. From the Developer top-level menu, select
ICE $>$ Launch New Instance. This will display a dialog asking you which new
plugins you'd like to include as part of the new ICE instance.
\begin{center} \includegraphics[width=\textwidth]{figures/combdev}
\end{center}
Select \texttt{org.eclipse.ice.fern} and click Ok. This will create and launch a
new instance of ICE that includes your custom Item plugin.
With a new ICE instance open, close the Welcome view if necessary and go to
\texttt{File $>$ New $>$ Other} and select the Create Item Wizard.
......@@ -167,17 +313,10 @@ input file, along with its dependent network and rate files.
At this point, if you had Fern built on your local machine, or if you had it
built on some remote host, you could configure that in the Hosts table. ICE
would then execute Fern based on that input. Since, for the purposes of this
tutorial, we don't have either of those configurations, we can use a third mode
of execution - launching our application via Docker. To do so, check the Launch
with Docker button, which will show a drop down widget populated with the list
of locally available Docker images. Select the eclipseice/fern image, and make
sure that the host table is configured to localhost and that the install path is
\texttt{/usr/bin}. Then simply launch Fern by clicking Go. This will pop up some
dialogs related to the connection of ICE to the Docker container, simply provide
a master password for Eclipse secure storage, and select yes on the known hosts
dialog.
would then execute Fern based on that input.
After the execution you should see the results in the Console, as shown below.
\begin{center} \includegraphics[width=\textwidth]{figures/launcherResult}
\end{center}
The execution should have produced a CSV file with the computed populations. You
can double-click that file to view them graphically in the ICE Plot Editor.
/main.aux
/main.log
/main.out
/main.pdf
......@@ -2,6 +2,5 @@
<classpath>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.7"/>
<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
<classpathentry kind="src" path="src/"/>
<classpathentry kind="output" path="target/classes"/>
</classpath>
......@@ -2,13 +2,14 @@ bin.includes = META-INF/,\
.,\
splash.bmp,\
plugin.xml,\
plugin_customization.ini,\
plugin_customization_runtime.ini,\
icons/,\
plugin.properties,\
about.html,\
about.ini,\
about.mappings,\
about.properties
about.properties,\
plugin_customization_sdk.ini
output.. = bin/
src.includes = META-INF/,\
build.properties,\
......
......@@ -2,11 +2,11 @@
<?eclipse version="3.4"?>
<plugin>
<extension
id="product"
id="sdk_product"
point="org.eclipse.core.runtime.products">
<product
application="org.eclipse.ui.ide.workbench"
description="The Eclipse Integrated Computational Environment"
description="The Eclipse Integrated Computational Environment SDK"
name="ICE">
<property
name="appName"
......@@ -42,12 +42,53 @@
</property>
<property
name="preferenceCustomization"
value="plugin_customization.ini">
value="plugin_customization_sdk.ini">
</property>
</product>
</extension>
<extension
id="runtime_product"
point="org.eclipse.core.runtime.products">
<product
application="org.eclipse.ui.ide.workbench"
description="The Eclipse Integrated Computational Environment"
name="ICE">
<property
name="aboutText"
value="%aboutText">
name="appName"
value="ICE">
</property>
</product>
<property
name="applicationXMI"
value="org.eclipse.platform/LegacyIDE.e4xmi">
</property>
<property
name="cssTheme"
value="org.eclipse.e4.ui.css.theme.e4_default">
</property>
<property
name="startupForegroundColor"
value="4A95FF">
</property>
<property
name="startupMessageRect"
value="7,485,665,20">
</property>
<property
name="startupProgressRect"
value="5,470,665,15">
</property>
<property
name="applicationCSSResources"
value="platform:/plugin/org.eclipse.platform/images/">
</property>
<property
name="windowImages"
value="/icons/ice_logo_16x16.png,/icons/ice_logo_32x32.png,/icons/ice_logo_64x64.png,/icons/ice_logo_128x128.png,/icons/ice_logo_256x256.png">
</property>
<property
name="preferenceCustomization"
value="plugin_customization_runtime.ini">
</property>
</product>
</extension>
</plugin>
org.eclipse.ui/SHOW_PROGRESS_ON_STARTUP = true
org.eclipse.ui/defaultPerspectiveId=org.eclipse.ice.client.widgets.perspective
\ No newline at end of file
org.eclipse.ui/SHOW_PROGRESS_ON_STARTUP = true
org.eclipse.ui/defaultPerspectiveId=org.eclipse.pde.ui.PDEPerspective
/*******************************************************************************
* Copyright (c) 2012, 2014 UT-Battelle, LLC.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Initial API and implementation and/or initial documentation - Jay Jay Billings,
* Jordan H. Deyton, Dasha Gorin, Alexander J. McCaskey, Taylor Patterson,
* Claire Saunders, Matthew Wang, Anna Wojtowicz
*******************************************************************************/
package org.eclipse.ice.client.rcp;
import org.eclipse.ice.client.common.ClientWorkbenchWindowAdvisor;
import org.eclipse.ui.application.IWorkbenchWindowConfigurer;
import org.eclipse.ui.application.WorkbenchAdvisor;
import org.eclipse.ui.application.WorkbenchWindowAdvisor;
public class EclipseClientWorkbenchAdvisor extends WorkbenchAdvisor {
private static final String PERSPECTIVE_ID = "org.eclipse.ice.client.widgets.perspective"; //$NON-NLS-1$
@Override
public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(
IWorkbenchWindowConfigurer configurer) {
configurer.setShowPerspectiveBar(true);
return new ClientWorkbenchWindowAdvisor(configurer);
}
@Override
public String getInitialWindowPerspectiveId() {
return PERSPECTIVE_ID;
}
}
......@@ -131,7 +131,7 @@ public class FernModel extends Model {
// Create the initial conditions section
DataComponent initConditionsComp = new DataComponent();
initConditionsComp.setName("Initial Conditions");
initConditionsComp.setName("initialConditions");
initConditionsComp.setId(2);
initConditionsComp
.setDescription("The parameters " + "needed to describe the initial " + "conditions for the problem");
......@@ -168,10 +168,21 @@ public class FernModel extends Model {
initConditionsComp.addEntry(initialTimeStep);
initConditionsComp.addEntry(density);
DataComponent outputComp = new DataComponent();
outputComp.setName("output");
outputComp.setDescription("The parameters needed to output data.");
outputComp.setId(3);
StringEntry popFile = new StringEntry();
popFile.setName("popFile");
popFile.setDescription("The name of the output populations file");
popFile.setDefaultValue("popFile.csv");
// Add the components to the Form
form.addComponent(networkComp);
form.addComponent(initConditionsComp);