Commit 40293582 authored by Jay Jay Billings's avatar Jay Jay Billings
Browse files

Merge remote-tracking branch 'origin/next' for 2.2-RC1.


Signed-off-by: default avatarJay Jay Billings <billingsjj@ornl.gov>
parents 76a043f5 2a6db9ac
/bin/
/tmp/
/ice-fullTutoria.synctex.gz
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>all</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>net.sourceforge.texlipse.builder.TexlipseBuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>net.sourceforge.texlipse.builder.TexlipseNature</nature>
</natures>
</projectDescription>
#TeXlipse project settings
#Tue Apr 12 13:38:16 EDT 2016
markTmpDer=true
builderNum=2
outputDir=bin
makeIndSty=
bibrefDir=
outputFormat=pdf
tempDir=tmp
mainTexFile=main.tex
outputFile=ice-fullTutorial.pdf
langSpell=en
markDer=true
srcDir=src
/main.aux
/main.log
/main.out
%%This is a very basic article template.
%%There is just one section and two subsections.
\documentclass{report}
\usepackage{authblk}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{caption}
\usepackage{subcaption}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{color}
\usepackage{url}
\usepackage[section]{placeins}
\setlength{\parskip}{1em}
\definecolor{dkgreen}{rgb}{0,0.6,0}
\definecolor{gray}{rgb}{0.5,0.5,0.5}
\definecolor{mauve}{rgb}{0.58,0,0.82}
\lstset{frame=tb,
language=Java,
aboveskip=3mm,
belowskip=3mm,
showstringspaces=false,
columns=flexible,
basicstyle={\small\ttfamily},
numbers=none,
numberstyle=\tiny\color{gray},
keywordstyle=\color{blue},
commentstyle=\color{dkgreen},
stringstyle=\color{mauve},
breaklines=true,
breakatwhitespace=true,
tabsize=3
}
\lstset{basicstyle=\ttfamily,
showstringspaces=false,
commentstyle=\color{red},
keywordstyle=\color{blue}
}
\setlength{\parskip}{1em}
\begin{document}
\title{Eclipse ICE User Manual}
\author{Jay Jay Billings}
\author{Andrew Bennett}
\author{Alex McCaskey}
\author{Robert Smith}
\author{Greg Watson}
\affil{Oak Ridge National Laboratory}
\maketitle{}
\chapter{Installation Details}
\graphicspath{{../../installation/src/}}
\input{../../installation/src/content}
\chapter{The Eclipse ICE Item Project Generator}
\graphicspath{{../../newItemGeneration/src/}}
\input{../../newItemGeneration/src/content}
\chapter{Working with Resource Components}
\graphicspath{{../../resourceComponents/src/}}
\input{../../resourceComponents/src/content}
\chapter{Dynamically Extending the Eclipse ICE UI}
\graphicspath{{../../dynamicUI/src/}}
\input{../../dynamicUI/src/content}
\chapter{Scripting}
\graphicspath{{../../scripting/src/}}
\lstset{inputpath=../../scripting/src/}
\input{../../scripting/src/content}
\chapter{The Eclipse ICE Developer Menu}
\graphicspath{{../../developerMenu/src/}}
\input{../../developerMenu/src/content}
\chapter{Geometry Editor}
\graphicspath{{../../geometryEditor/src/}}
\input{../../geometryEditor/src/content}
\chapter{Mesh Editor}
\graphicspath{{../../meshEditor/src/}}
\input{../../meshEditor/src/content}
%\input{../../moose-tutorial/src/content.tex} % FIXME! Incorrect structure.
%\chapter{Simulating Neutron Reflectivity}
%\graphicspath{{../../reflectivity/src/}}
%\input{../../reflectivity/src/content}
\chapter{Visualization}
\graphicspath{{../../visualization/src/}}
\input{../../visualization/src/content}
\chapter{Paraview}
\graphicspath{{../../paraviewTutorial/src/}}
\input{../../paraviewTutorial/src/content}
\end{document}
#TeXlipse project settings
#Mon Jan 18 18:15:25 EST 2016
#Tue Apr 12 14:10:07 EDT 2016
markTmpDer=true
builderNum=2
outputDir=bin
outputDir=bin/
makeIndSty=
bibrefDir=
outputFormat=pdf
......@@ -11,4 +11,4 @@ mainTexFile=main.tex
outputFile=developerMenu.pdf
langSpell=en
markDer=true
srcDir=src
srcDir=src/
\subsection*{Overview}
The Eclipse Integrated Computational Environment (ICE) has had a great track
record of providing a comprehensive environment for general scientific
computing. Tasks such as model input generation, local and remote simulation
execution, and post-simulation data analysis and visualization are all very well
supported in the application. These tasks take care of the majority of needs
for \emph{using} general scientific computing codes, but what about
\emph{developing} those applications to begin with? Is there any way ICE can be
extended to provide support for the development of science codes?
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/icemenu.png}
\centering
\caption{The ICE Developer Menu}
\label{fig:devmenu}
\end{figure}
The answer is yes! In 2015 ICE was extended to provide support for scientific
application \emph{development} through a custom, extensible \textbf{Developer}
top-level menu. This menu is shown in Figure
\ref{fig:devmenu} and provides custom actions that enable efficient scientific
application development for both novice and expert users of a given science
code.
The Developer Menu is completely customizable through Eclipse Extension Points.
Specifically, ICE exposes a new extension point:
\emph{org.eclipse.ice.developer.code}. This extension point provides the means
to specify details about a scientific code: its name, category (Framework,
Nuclear, Other, etc\ldots), and where its repository is hosted, just to name a
few. This point also enables the addition of \emph{commands} that point to some
custom subclass of \emph{org.eclipse.core.commands.AbstractHandler} that
performs some task related to the development of the code.
With these extensions exposed as part of an ICE product execution, ICE
handles all the complexity of picking them up and populating the Developer Menu
dynamically at runtime. This feature is shown in Figure \ref{fig:devcloneice},
with an ICE category for ICE development, and another for scientific frameworks.
This process is exactly how ICE developers work on ICE itself - by pulling down
the ICE binary and leveraging the Developer Menu to clone and build ICE, all
within ICE. ICE also provides these hooks for other scientific codes, like the
Multiphysics Object Oriented Simulation Environment (MOOSE) for general
finite-element simulations. ICE provides a hook for cloning MOOSE and for
forking a templated repository for MOOSE Application development.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/menu.png}
\caption{The Developer Menu ICE and MOOSE Actions}
\label{fig:devcloneice}
\end{figure}
Extending the Developer Menu is easy, and relies on simply creating a new plugin
and exposing a new extension. Let's see how to do this task in detail:
\subsection*{Extending the ICE Developer Menu}
For this tutorial, we are going to create a hook into the Developer menu to
clone a scientific code called Fern. Fern is an application that provides an
efficient nuclear reaction network solver. It is hosted at
\url{https://github.com/jayjaybillings/fern}.
To get started, we need to download the ICE plugins to our workspace, which we
can actually do through the Developer menu (pretty cool to use the Developer
menu to extend the Developer menu!). Click Developer $>$ ICE $>$ Clone ICE to
get all of ICE's plugins into the workspace. With ICE cloned to the workspace,
we can now begin to extend the Developer menu. First, we will need to create a
new plugin.
\subsubsection*{Create a New Plugin Project}
Creating a new plugin for an extension to the ICE Developer menu is simple, just
click File $>$ New $>$ Plugin Project (or Other, then select Plugin Project).
When the wizard opens, name your new plugin with something similar to Figure
\ref{fig:newplugin} and deselect the \texttt{Generate an activatitor} option. On
the next page, simply uncheck the create a plugin from template button and click Finish.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/combinedplugin.png}
\caption{Creating a new Plugin Project}
\label{fig:newplugin}
\end{figure}
When the MANIFEST.MF file editor opens up, add the
\emph{org.eclipse.ice.developer} plugin as a Required Plugin on the Dependencies
tab.
\subsubsection*{Create a New ICE Developer Extension}
Now let's create a new Extension to connect ICE and the Developer Menu
with a Clone Fern action. To do so, go to the Extensions tab of the
plugin MANIFEST file and click add. ICE provides an
org.eclipse.ice.developer.code extension point that lets users define various
details about their codes.
% \ref{fig:createExtPt} and click Finish.
% \begin{figure}[h]
% \includegraphics[width=\textwidth]{figures/extensionPt.png}
% \caption{Create a new ICE Scientific Code Extension}
% \label{fig:createExtPt}
% \end{figure}
You will then be presented with the view in Figure \ref{fig:config1}. Enter a
descriptive ID and Name for this extension and click Save.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/extptconfig1.png}
\caption{Configure the ID and Name of this Code Extension.}
\label{fig:config1}
\end{figure}
To define your scientific application, right click on the
org.eclipse.ice.developer.code extension in the All Extensions section and
select New $>$ Code in the context menu. This action will present you with the
view in Figure \ref{fig:config2} where you can select the code category, code
display name, the repository URL, and the branch you would like to work with.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/comb.png}
\caption{Create a new Code description for this extension.}
\label{fig:config2}
\end{figure}
To create a new developer action for your code, right click the code element of
the extension tree and select New $>$ Command. You will then be presented
with the view at the top of Figure \ref{fig:config2} where you can input the
name of this action and the AbstractHandler subclass that performs the action.
ICE provides a default GitCloneHandler that you may select. For this tutorial,
select that and click Save. You should now have a view similar to the bottom of
Figure \ref{fig:config2}.
% \begin{figure}[h]
% \includegraphics[width=.9\textwidth]{figures/extptconfig4.png}
% \caption{Create a new command for this code extension.}
% \label{fig:config4}
% \end{figure}
\subsubsection*{Setup ICE to Run with the New Plugin}
To see this new Developer command in action, we need to launch a new instance of
ICE. This can be done by opening the Run Configurations Wizard in Run $>$ Run
Configurations. Under the Eclipse Applications element in the tree on the left,
select the ICE launch configuration for your OS. Open the Plugins tab and add
your new developer plugin (see Figure \ref{fig:launch}) by enabling it. Then,
click Run to launch ICE with your developer plugin.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/launch.png}
\caption{Add your plugin to the run configuration.}
\label{fig:launch}
\end{figure}
With ICE running, navigate to the Developer menu and select Nuclear $>$ Fern $>$
Clone Fern (see Figure \ref{fig:clonefern}).
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/cloned.png}
\caption{Use the Developer Menu to Clone ICE.}
\label{fig:clonefern}
\end{figure}
This will kick off the action you specified to clone the Fern repository and
pull in any Eclipse projects to the workspace, as shown in Figure
% \ref{fig:result}
% \begin{figure}[h]
% \includegraphics[width=\textwidth]{figures/result.png}
% \label{fig:result}
% \end{figure}
\ No newline at end of file
\documentclass{article}
\documentclass{report}
%\documentclass[11pt,letterpaper,twoside,english,final]{article}
\usepackage{graphicx}
\usepackage{caption}
......@@ -7,162 +7,7 @@
\begin{document}
\section*{The Eclipse ICE Developer Menu}
\chapter{The Eclipse ICE Developer Menu}
\input{content}
\subsection*{Overview}
The Eclipse Integrated Computational Environment (ICE) has had a great track
record of providing a comprehensive environment for general scientific
computing. Tasks such as model input generation, local and remote simulation
execution, and post-simulation data analysis and visualization are all very well
supported in the application. These tasks take care of the majority of needs
for \emph{using} general scientific computing codes, but what about
\emph{developing} those applications to begin with? Is there any way ICE can be
extended to provide support for the development of science codes?
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/icemenu.png}
\centering
\caption{The ICE Developer Menu}
\label{fig:devmenu}
\end{figure}
The answer is yes! In 2015 ICE was extended to provide support for scientific
application \emph{development} through a custom, extensible \textbf{Developer}
top-level menu. This menu is shown in Figure
\ref{fig:devmenu} and provides custom actions that enable efficient scientific
application development for both novice and expert users of a given science
code.
The Developer Menu is completely customizable through Eclipse Extension Points.
Specifically, ICE exposes a new extension point:
\emph{org.eclipse.ice.developer.code}. This extension point provides the means
to specify details about a scientific code: its name, category (Framework,
Nuclear, Other, etc\ldots), and where its repository is hosted, just to name a
few. This point also enables the addition of \emph{commands} that point to some
custom subclass of \emph{org.eclipse.core.commands.AbstractHandler} that
performs some task related to the development of the code.
With these extensions exposed as part of an ICE product execution, ICE
handles all the complexity of picking them up and populating the Developer Menu
dynamically at runtime. This feature is shown in Figure \ref{fig:devcloneice},
with an ICE category for ICE development, and another for scientific frameworks.
This process is exactly how ICE developers work on ICE itself - by pulling down
the ICE binary and leveraging the Developer Menu to clone and build ICE, all
within ICE. ICE also provides these hooks for other scientific codes, like the
Multiphysics Object Oriented Simulation Environment (MOOSE) for general
finite-element simulations. ICE provides a hook for cloning MOOSE and for
forking a templated repository for MOOSE Application development.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/menu.png}
\caption{The Developer Menu ICE and MOOSE Actions}
\label{fig:devcloneice}
\end{figure}
Extending the Developer Menu is easy, and relies on simply creating a new plugin
and exposing a new extension. Let's see how to do this task in detail:
\subsection*{Extending the ICE Developer Menu}
For this tutorial, we are going to create a hook into the Developer menu to
clone a scientific code called Fern. Fern is an application that provides an
efficient nuclear reaction network solver. It is hosted at
\url{https://github.com/jayjaybillings/fern}.
To get started, we need to download the ICE plugins to our workspace, which we
can actually do through the Developer menu (pretty cool to use the Developer
menu to extend the Developer menu!). Click Developer $>$ ICE $>$ Clone ICE to
get all of ICE's plugins into the workspace. With ICE cloned to the workspace,
we can now begin to extend the Developer menu. First, we will need to create a
new plugin.
\subsubsection*{Create a New Plugin Project}
Creating a new plugin for an extension to the ICE Developer menu is simple, just
click File $>$ New $>$ Plugin Project (or Other, then select Plugin Project).
When the wizard opens, name your new plugin with something similar to Figure
\ref{fig:newplugin} and deselect the Generate an activation button. On the next
page, simply uncheck the create a plugin from template button and click Finish.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/combinedplugin.png}
\caption{Creating a new Plugin Project}
\label{fig:newplugin}
\end{figure}
When the MANIFEST.MF file editor opens up, add the
\emph{org.eclipse.ice.developer} plugin as a Required Plugin on the Dependencies
tab.
\subsubsection*{Create a New ICE Developer Extension}
Now let's create a new Extension to connect ICE and the Developer Menu
with a Clone Fern action. To do so, go to the Extensions tab of the
plugin MANIFEST file and click add. ICE provides an
org.eclipse.ice.developer.code extension point that lets users define various
details about their codes.
% \ref{fig:createExtPt} and click Finish.
% \begin{figure}[h]
% \includegraphics[width=\textwidth]{figures/extensionPt.png}
% \caption{Create a new ICE Scientific Code Extension}
% \label{fig:createExtPt}
% \end{figure}
You will then be presented with the view in Figure \ref{fig:config1}. Enter a
descriptive ID and Name for this extension and click Save.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/extptconfig1.png}
\caption{Configure the ID and Name of this Code Extension.}
\label{fig:config1}
\end{figure}
To define your scientific application, right click on the
org.eclipse.ice.developer.code extension in the All Extensions section and
select New $>$ Code in the context menu. This action will present you with the
view in Figure \ref{fig:config2} where you can select the code category, code
display name, the repository URL, and the branch you would like to work with.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/comb.png}
\caption{Create a new Code description for this extension.}
\label{fig:config2}
\end{figure}
To create a new developer action for your code, right click the code element of
the extension tree and select New $>$ Command. You will then be presented
with the view at the top of Figure \ref{fig:config2} where you can input the
name of this action and the AbstractHandler subclass that performs the action.
ICE provides a default GitCloneHandler that you may select. For this tutorial,
select that and click Save. You should now have a view similar to the bottom of
Figure \ref{fig:config2}.
% \begin{figure}[h]
% \includegraphics[width=.9\textwidth]{figures/extptconfig4.png}
% \caption{Create a new command for this code extension.}
% \label{fig:config4}
% \end{figure}
\subsubsection*{Setup ICE to Run with the New Plugin}
To see this new Developer command in action, we need to launch a new instance of
ICE. This can be done by opening the Run Configurations Wizard in Run $>$ Run
Configurations. Under the Eclipse Applications element in the tree on the left,
select the ICE launch configuration for your OS. Open the Plugins tab and add
your new developer plugin (see Figure \ref{fig:launch}) by enabling it. Then,
click Run to launch ICE with your developer plugin.
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/launch.png}
\caption{Add your plugin to the run configuration.}
\label{fig:launch}
\end{figure}
With ICE running, navigate to the Developer menu and select Nuclear $>$ Fern $>$
Clone Fern (see Figure \ref{fig:clonefern}).
\begin{figure}[h]
\includegraphics[width=\textwidth]{figures/cloned.png}
\caption{Use the Developer Menu to Clone ICE.}
\label{fig:clonefern}
\end{figure}
This will kick off the action you specified to clone the Fern repository and
pull in any Eclipse projects to the workspace, as shown in Figure
% \ref{fig:result}
% \begin{figure}[h]
% \includegraphics[width=\textwidth]{figures/result.png}
% \label{fig:result}
% \end{figure}
\end{document}
\section{Dynamic UI}
This tutorial will show you how to create custom, dynamic UI extensions to
Eclipse ICE.
What you will need for this tutorial:
\begin{itemize}
\item Experience creating Eclipse plugins
\item Experience writing UI code with SWT
\item Experience creating an ICE Item
\end{itemize}
\subsection{Introduction}
ICE makes some educated guesses based on the type of your components and
information that it can glean from your data to figure out the best way that it
can generate the the UI. However, after you create your first set of Items, you
might find yourself wondering if you can change the way that ICE auto-generates
the UI to better fit your needs. ICE lets you do this by setting the Context of
your Form and Components with the setContext() operation. Setting the context
with a string that is unique to your project will let ICE look up UI extensions
that you create and publish through the Eclipse 4 framework.
There are several important things to consider before you start extending the
UI. First, how much work do you want to do? Some of the UI constructs in ICE
are quick to change, such as EntryComposites for showing Entries, but others,
like GeometryPage and MeshPage, could require significant work because of the
level of graphics involved.
This tutorial will show you how to change two pieces of ICE’s UI: The page for
showing GeometryComponents and an EntryComposite. We will only show you how to
change the GeometryPage, not how to actually generate new 3D graphics. The
source code for this tutorial is in the ICE repo in a project called
org.eclipse.ice.demo.
\subsection{Create an ICE Item Project}
Use the ICE Item Project Generation Wizard to create a new Item with a
GeometryComponent and a DataComponent with one Entry in the Form. You can copy
the following code into your setupForm() operation:
\begin{lstlisting}[language=java]
@Override
public void setupForm() {
form = new Form();
ioService = getIOService();
// Create a geometry component
GeometryComponent geomComp = new GeometryComponent();
geomComp.setName("Geometry");
geomComp.setDescription("A geometry");
geomComp.setContext("demo-geometry");
geomComp.setGeometry(
new ShapeController(new Shape(), new BasicView()));
// Create a data component
DataComponent dataComp = new DataComponent();
dataComp.setName("Data");
dataComp.setDescription("Some Data");
dataComp.setContext("demo");
// Need to set the id since geomComp is number 1
dataComp.setId(2);
// Create an Entry for the data component
IEntry entry = new StringEntry();
entry.setName("Data Entry");
entry.setDescription("An Entry with Important Data");
entry.setContext("demo-entry");
// Add the Entry to the data component
dataComp.addEntry(entry);
// Add both components to the Form, showing the data component first.
form.addComponent(dataComp);
form.addComponent(geomComp);
// Set the context on the Form
form.setContext("demo");
return;
}
\end{lstlisting}
Note that your import packages lines should look this the following:
\begin{lstlisting}[language=java]
import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.eavp.viz.service.modeling.AbstractView;
import org.eclipse.eavp.viz.service.modeling.ShapeController;
import org.eclipse.eavp.viz.service.modeling.ShapeMesh;
import org.eclipse.ice.datastructures.entry.IEntry;
import org.eclipse.ice.datastructures.entry.StringEntry;
import org.eclipse.ice.datastructures.form.DataComponent;
import org.eclipse.ice.datastructures.form.Form;
import org.eclipse.ice.datastructures.form.FormStatus;
import org.eclipse.ice.datastructures.form.GeometryComponent;
import org.eclipse.ice.io.serializable.IIOService;
import org.eclipse.ice.io.serializable.IReader;
import org.eclipse.ice.io.serializable.IWriter;
import org.eclipse.ice.item.model.Model;
\end{lstlisting}
You may need to add some of these packages to your Manifest file.
If you have not created an Item in ICE before, please see \texttt{the ICE Item
Generation tutorial} to do this.
Add this plugin to the launch configuration for your system, launch ICE and
make sure that you can successfully create a DemoModel Item. You should have
see a Form with two pages as in figures \ref{fig:iceDefaultEntryPage} and
\ref{fig:iceDefaultGeometryPage}.
\begin{figure}[h]
\includegraphics[width=\textwidth]{pics/dynamicUI_defaultEntryPage.png}
\caption{Default Entry Composite on a Form}
\label{fig:iceDefaultEntryPage}
\end{figure}
\begin{figure}[h]
\includegraphics[width=\textwidth]{pics/dynamicUI_defaultGeometryPage.png}
\caption{Default Geometry Page}
\label{fig:iceDefaultGeometryPage}
\end{figure}
The rest of the tutorial will look at replacing the routine that draws the
Entry on the first page and the entire Geometry Page with your own custom page.
You won’t have to make any additional changes to your Item (assuming it works
as shown above). Note that in the code above we need to use different context
names for the Entry and the GeometryComponent so that the context can uniquely
identify the routines that draw each.
\subsection{Create an IPageProvider and IPageFactory}
We will replace the Geometry Page first. Create a new package.This requires two
pieces to properly locate your Page, through your IPageFactory, and to draw
your Page, through you IPageProvider.
Start by adding the following packages to your import packages block in your
Manifest file: