Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Developing MOOSE Applications with ICE"

(→‎Adding a New Kernel)
 
(67 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
−
This article is designed to walk MOOSE developers through a typical workflow for developing MOOSE-based applications in ICE. Since ICE is built on top of the Eclipse platform, a large variety of sophisticated software development tools and technologies for developing scientific software can be integrated into the ICE platform. Version control, code editing, code completion, code building, and code generation are just a few of the various technologies now available to MOOSE-based application developers using ICE. Additionally, after developing your custom MOOSE application, the usual MOOSELauncher and MOOSEModel Items and the ICE Visualization perspective are still at your disposal for constructing input files, launching jobs, and visualizing results.
+
This article is designed to guide users through a typical workflow for developing MOOSE-based applications in ICE. Since ICE is built on top of the Eclipse platform, a large variety of sophisticated tools and technologies for developing scientific software can be leveraged for developing MOOSE applications.
 +
 
 +
Version control, code editing, code completion, code building, and code generation are just a few of the technologies available to MOOSE-based application developers using ICE. Additionally, after the user develops a custom MOOSE application, the usual MOOSELauncher and MOOSEModel items—along with the ICE Visualization perspective—are still at their disposal for constructing input files, launching jobs, and visualizing results.
 +
 
 +
=== Prerequisites ===
 +
 
 +
To use the MOOSE support in ICE, the user will need to have MOOSE installed on their system along with any MOOSE-based application that the user would like to run. The user can simply use "moose_test" as the project name if no other application is available (the example in this tutorial uses the name "animals").
 +
 
 +
Please note that installing MOOSE requires the user to add several packages (prerequisites) to their system. For more information on how to install MOOSE and the prerequisites for doing so, please check out the MOOSE [http://www.mooseframework.org/getting-started Getting Started] guide.
 +
 
 +
For Mac OS X users, ICE developers also recommend installing the [http://brew.sh/ Homebrew package manager] to ensure all required packages and their dependencies are available to the user.
  
 
== Cloning MOOSE ==
 
== Cloning MOOSE ==
−
To clone MOOSE, simply switch to the Git Perspective in the top right corner of ICE. You will be presented with the following view.  
+
The latest version of ICE makes cloning MOOSE very simple.
 +
 
 +
In the main ICE window, click ''Developer'' > ''Framework'' > ''MOOSE'' > ''Clone Moose.''
 +
 
 +
[[File:Clone_moose_dev_menu_stc.png]]
 +
 
 +
This step will automatically connect to the MOOSE GitHub repository, create a local clone on the user's disk, and import MOOSE into the "Project Explorer."
 +
 
 +
[[File:Moose_project_explorer_stc.png]]
 +
 
 +
<!-- I have commented out the old method, below. -->
 +
<!-- To clone MOOSE, the user will need to switch to the Git Perspective.
 +
 
 +
Click the ''Open Perspective'' button in the upper right hand corner of ICE, denoted below with an orange arrow.
 +
 
 +
[[File:open_git_perspective_stc_1.png]]
 +
 
 +
Then select ''Git'' from the list and click ''OK''.
 +
 
 +
[[File:open_git_perspective_stc_2.png]]
 +
 
 +
The user will be presented with the following view.
 +
 
 +
In this view, click on the ''Clone a Git Repository'' button in the toolbar or click the hyperlink in the middle of the view (visible only if the user has no existing Git repositories in their file history).
 +
 
 +
[[File:clone_git_button_stc.png]]
  
−
[[File:GitView.png]]
+
A wizard will prompt the user to provide information for the Git repository they are attempting to use.
  
−
Now click the 'Clone a Git Repository' button in the toolbar of the 'Git Repository' view (or the hyperlink in the middle of the view if you have not repositories). You will be presented with the following wizard.  
+
For MOOSE, enter <tt>https://github.com/idaholab/moose</tt> into the "URI" field and select ''Next''.
  
 
[[File:clone_wizard.png]]
 
[[File:clone_wizard.png]]
 +
 +
On the next screen, the user must select the branches they would like to clone. With the selection made, click ''Next''.
 +
 
[[File:clone_wizard2.png]]
 
[[File:clone_wizard2.png]]
 +
 +
The last screen allows the user to specify the clone location on their local filesystem. To place the clone in the local ICE workspace, enter <tt>~/ICEFiles/moose</tt> in the field and click ''Finish''.
 +
 
[[File:clone_wizard3.png]]
 
[[File:clone_wizard3.png]]
  
−
Enter https://github.com/idaholab/moose into the URI entry and select next. This will present you with the branch selection wizard page. Select which branches you'd like to import in this clone and click Next. The last page will let you specify the clone location on your local filesystem. If you'd like this to be in your local ICE workspace entry /home/username/ICEFiles in the entry and click Finish.  
+
The Git repository is then cloned to the user's local disk.
  
−
To import MOOSE into your ICE Project Explorer, simply right click the created moose repository in the Git Repository view and select 'Import Projects'. On the first wizard page, select 'Import as New Project' and click finish. This will present you with the ICE New Project wizard. In this wizard, open the C/C++ tree node and select 'Makefile project with Existing Code'. Provide a valid project name and toolchain and click finish. You should see MOOSE in your Project Explorer.
+
[[File:Git_clone_progress_stc.png]]
  
−
[[File:import_git_proj.png]]
+
After the clone completes, the user will be presented with a "Git Repository" view.
 +
 
 +
To import MOOSE into the ICE "Project Explorer," simply right click the MOOSE repository and select ''Import Projects''. This will present the user with the import wizard.
 +
 
 +
[[File:Import_git_projects_stc.png]]
 +
 
 +
On the first wizard page, select ''Import using the New Project wizard'' and click ''Finish''. This will present the user with the ICE "New Project" wizard.
 +
 
 +
From here, open the C/C++ tree node and select ''Makefile project with Existing Code''. Provide a valid project name and toolchain and click ''Finish.''
 +
 
 +
MOOSE should now appear in the user's "Project Explorer."
 +
 
 +
[[File:import_git_proj.png]]-->
  
 
== Building MOOSE ==  
 
== Building MOOSE ==  
−
To build MOOSE/Libmesh within ICE, open the Make Target view by going to Window > Show View > Other and search and select Make Target. With MOOSE imported into your Project Explorer, you should see the MOOSE project in the Make Target view. Right click on that project and select New. A dialog will pop up prompting you for the Make Target name, target name, and build command. Set the name as 'Build Libmesh', uncheck 'Same as target name' and leave the Make target blank, uncheck 'Use builder settings' and set the command as 'sh scripts/update_and_rebuild_libmesh.sh', then click 'Ok'. Now you should see a 'Build Libmesh' target, which upon double-clicking will execute the update_and_rebuild_libmesh.sh script with the output streaming in the Console view.  
+
The [[#Cloning MOOSE|Cloning MOOSE]] step above also creates the two required build targets used to build Libmesh and MOOSE. Libmesh is required for MOOSE to build, so the user should start there.
  
−
Once that is done, you can create another Make Target in the same manner, this time setting the target as all, but setting the build command (assuming you have CMake installed on your system) as 'cmake -E chdir framework make' (feel free to add -j N to this command, where N is the number of make threads). If you do not have CMake installed, you can right click on the MOOSE project in the Project Explorer and select Properties. In this Properties dialog, select C/C++ Build and append to the Build directory entry 'framework'. Now, double-clicking this make target will execute the MOOSE build, and you should see the output streaming in the Console.  
+
===Building Libmesh===
 +
The "Build Libmesh" build target will appear in the "Build Targets" view pane.
 +
 
 +
Double clicking the "Build Libmesh" target will execute the <tt>sh update_and_rebuild_libmesh.sh</tt> script with the output streaming in the "Console" view pane.
 +
 
 +
[[file:Moose_build_libmesh_stc_1.png]]
 +
 
 +
Note that this process will take some time.
 +
 
 +
[[file:Moose build libmesh stc-2.png]]
 +
 
 +
===Building MOOSE===
 +
Once the Libmesh build completes, the user can then execute the "Build MOOSE" target and the output should stream in the "Console" view pane.
 +
 
 +
[[file:Cmake_build_target_stc.png]]
 +
 
 +
Note that this process will take some time.
 +
 
 +
[[file:Moose_build_console_output_stc.png]]
 +
 
 +
With MOOSE built, the user can start the process of creating their own MOOSE-based application. The first step, "Forking the Stork," is described below.
  
 
== Forking the Stork ==
 
== Forking the Stork ==
−
The internal MOOSE development team provides another GitHub repository called stork at https://github.com/idaholab/stork that represents the base structure needed to create a new MOOSE application. So 'Forking the Stork' implies forking this repository, changing its name to whatever you've decided to call your MOOSE application, and cloning that locally to begin work. The MOOSE team calls this 'Forking the Stork' and provides a link to the repository at mooseframework.org/create-an-app.  
+
The MOOSE development team provides a GitHub repository called "stork" (located at https://github.com/idaholab/stork) that includes the base structure needed to create a new MOOSE application. So, "Forking the Stork"—as the MOOSE team coined it—implies forking this repository, changing its name to the name of the user's new MOOSE application, and cloning the contents of the repository to the user's local disk.
 +
 
 +
ICE provides this functionality through a simple interface, allowing an ICE user to "Fork the Stork" in a few short steps.
  
−
ICE now provides this functionality by going to Developer > Framework > MOOSE > Fork the Stork.
+
First, in the main ICE menu, select ''Developer'' > ''Framework'' > ''MOOSE'' > ''Fork the Stork''.
  
 
[[File:Fork_Path.png]]
 
[[File:Fork_Path.png]]
−
[[File:fork_dialog.png]]
 
  
−
This will present a new dialog asking for the name of your new MOOSE application, as well as your GitHub username and password. Upon providing this information and clicking 'Ok', ICE will fork the https://github.com/idaholab/stork repository for you, rename it to your provided application name, clone it to ~/ICEFiles, and import it into ICE as a new C++ project in the C/C++ perspective's Project Explorer view.
+
The resulting dialog will prompt the user for the name of their new MOOSE application ("animals" in this case), as well as their GitHub username and password.
 +
 
 +
[[File:fork_dialog.png]]
  
−
Additionally, the import generates a fully configured Make Target in the Make Target view, and sets up the C++ Indexer to point to your ICE MOOSE project's include files. This is essential for providing code completion and MOOSE code search while your developing your MOOSE application. To look at a MOOSE class that you've referenced in one of your application's source files, simply click the class name or the header file and click F3. ICE will take you directly to the declaration for that MOOSE class so that you can peruse and look up its method definitions.  
+
Once the user has provided this information and clicked ''Finish'', ICE will fork the "stork" repository (located at https://github.com/idaholab/stork), rename it to the provided application name, clone it to <tt>~/ICEFiles</tt> on the user's local disk, and import it into ICE as a new C++ project in the C/C++ perspective's "Project Explorer" view pane.
  
 
[[File:new_app.png]]
 
[[File:new_app.png]]
−
[[File:make_target.png]]
+
 
 +
To look at a MOOSE class referenced in one of the new MOOSE application's source files, simply click the class name or the header file and click F3. ICE will take the user directly to the declaration for that MOOSE class so they can peruse and look up its method definitions.
  
 
== Adding a New Kernel ==  
 
== Adding a New Kernel ==  
  
−
Once you've cloned and built MOOSE, and Forked the Stork to produce a new MOOSE application ready for development, you can easily create custom Kernels with ICE. To create a new Kernel, right click on your new MOOSE-based application project and select New > MOOSE Object > Kernel.  
+
The user can easily create custom Kernels with ICE once they have cloned, built, and "Forked the Stork" to produce a new MOOSE application.
 +
 
 +
To create a new Kernel, right click on the new MOOSE-based application project and select ''New'' > ''MOOSE Object'' > ''Kernel''.  
  
 
[[File:new_kernel.png]]
 
[[File:new_kernel.png]]
  
−
This action will display an input prompt asking for the name of your new Kernel subclass. Simply enter the name and push 'Ok'. Then ICE will automatically generate a new include and source file in include/kernel and source/kernel, respectively. The new files are the stubbed out, base implementation of a subclassed Kernel that you can then add to and modify.  
+
This action will prompt the user for the name of the new Kernel subclass.
 +
 
 +
Simply enter the desired name and click ''OK''.
 +
 
 +
[[file:kernel_name_dialog.png]]
 +
 
 +
ICE will automatically generate a new include and source file in <tt>include/kernel</tt> and <tt>src/kernel</tt>, respectively.
 +
 
 +
These new files are the stubbed out, base implementation of a subclassed Kernel can be modified to fit the user's operation.  
  
 
[[File:kernel_source.png]]
 
[[File:kernel_source.png]]
  
 
== Building your MOOSE App ==  
 
== Building your MOOSE App ==  
−
Building your MOOSE application is simple because the 'Fork the Stork' action produced a Make Target for you. Simply double-click that make target and you application will build, producing the application executable.  
+
Building the newly-created MOOSE application is simple because the "Fork the Stork" action also produced a build target (make all) for the user.
 +
 
 +
Navigate to the "Build Target" view pane and double click on ''make all'' (the new build target).
 +
 
 +
[[File:make_target.png]]
 +
 
 +
The new MOOSE application will then build, producing an application executable. Note that this will take some time.
 +
 
 +
[[file:animals_build_console_output.png]]
  
 
== Pushing Changes Back to GitHub ==  
 
== Pushing Changes Back to GitHub ==  
−
To push changes to the remote GitHub repository at https://github.com/username/animal, switch back to the Git perspective and click your applications git repository in the Git Repositories view. On the bottom right of the screen, you should see another set of tabbed views, one of them being the Git Staging view.  
+
As the user makes modifications to their project, they will want to periodically commit or "push" these changes to their GitHub repository.
 +
 
 +
===Git Perspective===
 +
 
 +
The first step is to open the "Git Perspective" by clicking the ''Open Perspective'' button in the upper right hand corner of ICE.
 +
 
 +
[[file:ICE_OpenPerspective.png]]
 +
 
 +
Next, select ''Git'' from the resulting prompt and click ''OK''.
 +
 
 +
[[file:Open_git_perspective_stc_2.png]]
 +
 
 +
The user should now have the ''Git'' perspective button available on the ICE toolbar.
 +
 
 +
[[file:Git_perspective_button_stc.png]]
 +
 
 +
Click the ''Git'' perspective button to bring up the Git interface pane in the main ICE window. The user should now see the repository for their MOOSE-based application in the "Git Repositories" view pane (left), "animals" in this case.
 +
 
 +
[[file:Git_repos_view_stc.png]]
 +
 
 +
===Push Changes===
 +
 
 +
To push project changes/modifications to the remote GitHub repository, switch to the Git perspective, as above, and select the desired repository in the "Git Repositories" view pane.
 +
 
 +
The "Git Repositories" view includes a new set of tabbed views. Select the ''Git Staging'' tab to pull up the "Git Staging" view pane.
 +
 
 +
[[file:Git_commit.png]]
 +
 
 +
Drag any "Unstaged Changes" to the "Staged Changes" section.
  
−
[[File:git_commit.png]]
+
Provide a brief message describing the nature of the commit.
  
−
Click the Git Staging View and drag any Unstaged Changes to the Staged Changes section. Now provide a brief commit message and click 'Commit and Push', enter your GitHub credentials, and watch as your files are committed to the remote repository!
+
Finally, click ''Commit and Push,'' enter the GitHub credentials if/when prompted, and watch as the new files are committed to the remote repository!
  
 
== Executing Built MOOSE Application ==
 
== Executing Built MOOSE Application ==
 
Now that you've developed a new MOOSE application you need to develop input files for it and execute it to see your desired results. This is simple with ICE: just use the built in MOOSE Model Builder and MOOSE Launcher Items. Detailed instructions can be found at [[Using MOOSE with ICE]].
 
Now that you've developed a new MOOSE application you need to develop input files for it and execute it to see your desired results. This is simple with ICE: just use the built in MOOSE Model Builder and MOOSE Launcher Items. Detailed instructions can be found at [[Using MOOSE with ICE]].

Latest revision as of 10:26, 23 November 2016

Introduction

This article is designed to guide users through a typical workflow for developing MOOSE-based applications in ICE. Since ICE is built on top of the Eclipse platform, a large variety of sophisticated tools and technologies for developing scientific software can be leveraged for developing MOOSE applications.

Version control, code editing, code completion, code building, and code generation are just a few of the technologies available to MOOSE-based application developers using ICE. Additionally, after the user develops a custom MOOSE application, the usual MOOSELauncher and MOOSEModel items—along with the ICE Visualization perspective—are still at their disposal for constructing input files, launching jobs, and visualizing results.

Prerequisites

To use the MOOSE support in ICE, the user will need to have MOOSE installed on their system along with any MOOSE-based application that the user would like to run. The user can simply use "moose_test" as the project name if no other application is available (the example in this tutorial uses the name "animals").

Please note that installing MOOSE requires the user to add several packages (prerequisites) to their system. For more information on how to install MOOSE and the prerequisites for doing so, please check out the MOOSE Getting Started guide.

For Mac OS X users, ICE developers also recommend installing the Homebrew package manager to ensure all required packages and their dependencies are available to the user.

Cloning MOOSE

The latest version of ICE makes cloning MOOSE very simple.

In the main ICE window, click Developer > Framework > MOOSE > Clone Moose.

Clone moose dev menu stc.png

This step will automatically connect to the MOOSE GitHub repository, create a local clone on the user's disk, and import MOOSE into the "Project Explorer."

Moose project explorer stc.png


Building MOOSE

The Cloning MOOSE step above also creates the two required build targets used to build Libmesh and MOOSE. Libmesh is required for MOOSE to build, so the user should start there.

Building Libmesh

The "Build Libmesh" build target will appear in the "Build Targets" view pane.

Double clicking the "Build Libmesh" target will execute the sh update_and_rebuild_libmesh.sh script with the output streaming in the "Console" view pane.

Moose build libmesh stc 1.png

Note that this process will take some time.

Moose build libmesh stc-2.png

Building MOOSE

Once the Libmesh build completes, the user can then execute the "Build MOOSE" target and the output should stream in the "Console" view pane.

Cmake build target stc.png

Note that this process will take some time.

Moose build console output stc.png

With MOOSE built, the user can start the process of creating their own MOOSE-based application. The first step, "Forking the Stork," is described below.

Forking the Stork

The MOOSE development team provides a GitHub repository called "stork" (located at https://github.com/idaholab/stork) that includes the base structure needed to create a new MOOSE application. So, "Forking the Stork"—as the MOOSE team coined it—implies forking this repository, changing its name to the name of the user's new MOOSE application, and cloning the contents of the repository to the user's local disk.

ICE provides this functionality through a simple interface, allowing an ICE user to "Fork the Stork" in a few short steps.

First, in the main ICE menu, select Developer > Framework > MOOSE > Fork the Stork.

Fork Path.png

The resulting dialog will prompt the user for the name of their new MOOSE application ("animals" in this case), as well as their GitHub username and password.

Fork dialog.png

Once the user has provided this information and clicked Finish, ICE will fork the "stork" repository (located at https://github.com/idaholab/stork), rename it to the provided application name, clone it to ~/ICEFiles on the user's local disk, and import it into ICE as a new C++ project in the C/C++ perspective's "Project Explorer" view pane.

New app.png

To look at a MOOSE class referenced in one of the new MOOSE application's source files, simply click the class name or the header file and click F3. ICE will take the user directly to the declaration for that MOOSE class so they can peruse and look up its method definitions.

Adding a New Kernel

The user can easily create custom Kernels with ICE once they have cloned, built, and "Forked the Stork" to produce a new MOOSE application.

To create a new Kernel, right click on the new MOOSE-based application project and select New > MOOSE Object > Kernel.

New kernel.png

This action will prompt the user for the name of the new Kernel subclass.

Simply enter the desired name and click OK.

Kernel name dialog.png

ICE will automatically generate a new include and source file in include/kernel and src/kernel, respectively.

These new files are the stubbed out, base implementation of a subclassed Kernel can be modified to fit the user's operation.

Kernel source.png

Building your MOOSE App

Building the newly-created MOOSE application is simple because the "Fork the Stork" action also produced a build target (make all) for the user.

Navigate to the "Build Target" view pane and double click on make all (the new build target).

Make target.png

The new MOOSE application will then build, producing an application executable. Note that this will take some time.

Animals build console output.png

Pushing Changes Back to GitHub

As the user makes modifications to their project, they will want to periodically commit or "push" these changes to their GitHub repository.

Git Perspective

The first step is to open the "Git Perspective" by clicking the Open Perspective button in the upper right hand corner of ICE.

ICE OpenPerspective.png

Next, select Git from the resulting prompt and click OK.

Open git perspective stc 2.png

The user should now have the Git perspective button available on the ICE toolbar.

Git perspective button stc.png

Click the Git perspective button to bring up the Git interface pane in the main ICE window. The user should now see the repository for their MOOSE-based application in the "Git Repositories" view pane (left), "animals" in this case.

Git repos view stc.png

Push Changes

To push project changes/modifications to the remote GitHub repository, switch to the Git perspective, as above, and select the desired repository in the "Git Repositories" view pane.

The "Git Repositories" view includes a new set of tabbed views. Select the Git Staging tab to pull up the "Git Staging" view pane.

Git commit.png

Drag any "Unstaged Changes" to the "Staged Changes" section.

Provide a brief message describing the nature of the commit.

Finally, click Commit and Push, enter the GitHub credentials if/when prompted, and watch as the new files are committed to the remote repository!

Executing Built MOOSE Application

Now that you've developed a new MOOSE application you need to develop input files for it and execute it to see your desired results. This is simple with ICE: just use the built in MOOSE Model Builder and MOOSE Launcher Items. Detailed instructions can be found at Using MOOSE with ICE.

Retrieved from "https://wiki.eclipse.org/index.php?title=Developing_MOOSE_Applications_with_ICE&oldid=412070"

This page was last modified 10:26, 23 November 2016 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top