Commit ba4dd57c authored by amccaskey's avatar amccaskey
Browse files

Pushing updates to new item gen tutorial doc


Signed-off-by: default avataramccaskey <mccaskeyaj@ornl.gov>
parent 08aa94d6
/main.aux
/main.log
/main.out
/main.aux
/main.log
/main.out
/main.pdf
\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}
......@@ -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}
\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:
\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():
......@@ -136,11 +280,13 @@ 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.
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
......@@ -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);
form.addComponent(outputComp);
// Set the Form ID info
form.setName(getName());
form.setDescription(getDescription());
......
......@@ -89,8 +89,6 @@ public class $className$Model extends Model {
form.setId(getId());
form.setItemID(getId());
loadDefault();
/* SetupForm Example:
*
* DataComponent data = new DataComponent();
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment