NairnFEAMPMViz

From OSUPDOCS
Revision as of 13:01, 29 August 2013 by Nairnj (talk | contribs)
Jump to navigation Jump to search

NairnFEAMPMViz is a Java application to create simulations, run them, and visualize them. This page needs conversion to the Media Wiki style.

Introduction

The nairn-mpm-fea project includes source code for a Java application called NairnFEAMPMViz that lets you create XML input files, run calculations, and visualize results for both NairnFEA and NairnFEA. The nairn-mpm-fea check out does not have the jar file for this application; you have two options:

  1. Visit the <a href="http://code.google.com/p/nairn-mpm-fea/downloads/list">download page</a> for this project. Periodically a recent compiled jar file along with a Windows-only clickable exe version will be posted. Simply download and run to start using NairnFEAMPMViz. (Note: that the <a href="http://code.google.com/p/nairn-mpm-fea/downloads/list">downloads page</a> does not have a clickable MacOS version of NairnFEAMPMViz because you should download and <a href="#nairnfeampm">use NairnFEAMPMM</a> instead; it is on the download page as well as a dmg or disk image file.)
  2. If you want the latest version (the <a href="http://code.google.com/p/nairn-mpm-fea/downloads/list">download version</a> may lag behind the current version) or if you want to make changes to the code, the other option is to <a href="#compile">compile the NairnFEAMPMViz source code</a> in this project.

Note that NairnFEAMPMViz requires a system with Java 1.5.0 (a.k.a Java 5) or newer installed.

Running NairnFEAMPMViz

If you <a href="http://code.google.com/p/nairn-mpm-fea/downloads/list">downloads page</a> the Windows exe version, just double click to start. The rest of this section is about starting the application using the jar file version.

You can start a Java application as a jar file by double clicking on the jar file. Although this works on most computers, the application will start with the default amount of memory for the Java Virtual Machine. The default memory is enough to open small calculations, but not enough for larger calculations. To start NairnFEAMPMViz with more memory, you should launch the Java application from a command line using:

java -Xmx512m -jar NairnFEAMPMViz.jar

The -Xmx option allocates the desired memory (where "m" means in megabytes). The -jar option gives a path to the compiled jar file (the above assumes you are in the same folder as the jat file).

When running in Windows, you can launch from a Windows command prompt or from a cygwin shell. In either case, you will need to include the path to the java command in your PATH environment variable. The path to Java executables in Windows will be something like: 

C:\Program Files\Java\jdk1.6.0_03\bin

Installation of java may add this path to your Windows environment for you; if not you will have to edit the system environment variables and add it. For cygwin, its $PATH variable does not use the Windows path; thus you will need to manually add the java path to cygwin's $PATH variable as well, perhaps in one of your login files (e.g., .bash_profile). You should add a path that will be similar to: 

/cygdrive/c/Files/Java/jdk1.6.0_03/bin

Note the use of forward slashes in cygwin instead of Window's back slashes.

Another method in Windows to launch NairnFEAMPMViz correctly is to create a simple batch file. The process is:

  • Make a copy of the file nairn-mpm-fea/Visualization/build/NairnFEAMPMVIz.bat and edit that copy. This file will contain something like 
    C:
chdir "C:\Documents and Settings\user\nairn-mpm-fea\Visualization\build"
java -Xmx512m -jar NairnFEAMPMViz.jar
    Edit the second line to be the full path to the folder with your NairnFEAMPMViz jar file (quote the path if it includes spaces in some directory names). The last line assumes your Windows environment includes the path to the java command. If note, you can replace java by the full path to the java executable.
  • Next create a short cut to the batch file (and give it any desired name). Right click on the new shortcut and select "Properties". In the properties window, click "Change Icon..." and "Browse..." for the NairnFEAMPMViz.ico file (in the nairn-mpm-fea/Visualization/build folder).
  • Finally, move the short cut to your desktop (or to any other folder). You can double click the shortcut to launch NairnFEAMPMViz ready for calculations and/or visualization.

Running NairnFEAMPMViz on a Remote Computer

To run NairnFEAMPMViz remotely (such as running from a terminal connected to a Linux cluster that has your code and calculation results), you have to log onto the remote computer using X11 terminal software and enable "trusted X11 forwarding." The command line is 

ssh -Y -l username servername

Once connected, start NairnFEAMPMViz using the java command line method described in the previous section.

Very Brief Usage Instructions

To use NairnFEAMPMViz:

  1. To edit input files and launch calculations, see the help on <a href="../running/index.html#javaviz">running the code</a>. Results run in NairnFEAMPMViz will automatically open for visualization when done.
  2. To open saved results for visualization use the "Open..." menu command or click the "Folder" icon. Note that "calculation results" are in the file of output text sent by NairnFEA or NairnMPM to standard output, and not one of the associated files written by NairnMPM. Once opened, the text results will appear in the top two sections of a new window. A control panel for visualizing results will appear in the bottom section.
  3. To plot results, select a plot type in the control panel area and then follow the blue line to select all available options for that type of plot.
  4. Finally, click the "Plot" button to get the plot in a new window. To plot different results, select new options and click the "Plot" button again (which may have changed to "Replot" or "Add Plot").
  5. For more details on use of NairnFEAMPM, click the "Help" button in the application.

Performance Issues

The nature of Java applications is that they are slower than compiled applications. Thus NairnFEAMPMViz is slower than <a href="#nairnfeampm">NairnFEAMPM</a>. The speed of NairnFEAMPMViz, however, is good. All internal calculations run fast. The slowest step is the time required to draw the graphics to the screen. Furthermore, this step is very system dependent. Running in MacOS is the fastest (but if you have MacOS, you may as well use <a href="#nairnfeampm">NairnFEAMPM</a> instead). Running in Windows is slower, but still good.

Running on a Linux machine using an X11 terminal is significantly slower, especially when any window with graphics is open. You will want to avoid this option, unless it is the only option available (i.e., when your only access to the data is through a remote login). The differences are caused by the system dependent Java virtual machines and between X11 and non-X11 uses by Java.


Compiling NairnFEAMPMViz Java Application

One option for creating new visualization tools, is to edit the NairnFEAMPMViz source code and create them. After editing, you will need to recompile the code as explained in this section. The options for working with the NairnFEAMPMViz source code are:

  • <a href="#unix">Compile using command line script</a>
  • <a href="#eclipse">Compile using Eclipse on any platform</a>

Command Line Compile

You can compile the code and create the jar file on a Unix/Linux command line by running the script called makejar that is located at:

nairn-mpm-fea/Visualization/build/makejar

When you run this script, it will compile the Java source code and create a self-contained jar file in that same directory. By default this script assumes compilation on Windows. To compile on Mac uses makejar -m. To compile on Linux, use makejar -l.

To run this script, you need the javac compiler and jar utility installed on your computer. Compilation requires Java 1.5.x or newer. It is available free on various platforms from <a href="http://java.sun.com/javase/">Sun's website</a> as part of the standard Java Development Kit (JDK) installation.

If the required javac and jar tools are not in the default path, you can edit the makejar file and enter the full path to each command (or add their paths to your $PATH environment variable). When using cygwin in Windows, the path to the java binaries will be something like: 

/cygdrive/c/Program Files/Java/jdk1.6.0_03/bin

Compiling Using Eclipse

<a href="http://www.eclipse.org" target="new">Eclipse</a> is an open-source and free development system for Java (and for other languages with the appropriate plug ins). This section explains how to import the code into an <a href="http://www.eclipse.org" target="new">Eclipse</a> project. This method was done using <a href="http://www.eclipse.org" target="new">Eclipse Indigo (3.7)</a>, which is available free for Windows, Mac, and other platforms. These steps will probably work for other versions too.

The first steps are to install and prepare <a href="http://www.eclipse.org" target="new">Eclipse</a> for Java development. These steps also need tools for subversion and are described <a href="index.html#geteclipse">here</a>. Be sure to do the optional step for Java development.

You are now ready to manage <a href="http://www.eclipse.org" target="new">Eclipse</a> projects using SVN. To start with a NairnFEAMPMViz project, do the following:

  1. Choose menu command "New → Project...", expand the "SVN" section, choose "Project from SVN" and click "Next."
  2. You will be asked to select an SVN repository. Enter the following settings followed by clicking "Next":
  3. Choose "Head Revision" for latest version or use date or revision options for older versions and then click "Next."
  4. Select "Check out as project with the name specified" and specify NairnFEAMPMViz. Click "Finish" and the project will be created. It should automatically build and be ready to run.
  5. To create a running option with sufficient memory, choose the "Run Configurations..." menu command
    1. Select "Java Application" and click the "New" icon to create a new runnable
    2. Enter any name such as "NairnFEAMPMViz with Memory."
    3. Enter "NairnFEAMPMViz" (or browse for it) into the Project field
    4. Enter "NairnFEAMPMViz" (or browse for it) into the Main class field
    5. Click on "Arguments" tab
    6. Enter "-Xmx512m" into the VM Arguments field (this command tells the Java machine to allocate 512 MB for running NairnFEAMPMViz. You can increase or decrease the memory as needed).
    7. Click "Apply"
    8. Click "Run" to run NairnFEAMPMViz
    9. In the future, you can run using the "NairnFEAMPMViz with Memory" item in the Run History menu

The above process will create a project in the <a href="http://www.eclipse.org" target="new">Eclipse</a> workspace that will have a copy of the files needed for the NairnFEAMPMViz project. You can update to the latest version by right clicking (or control clicking on Mac) the project name and selecting "Update" from the "Team" submenu. If you are certified as a project committer, you can save your changes by right clicking (or control clicking on Mac) on the project name and choosing "Team → Commit..."

The above process will let you compile and run NairnFEAMPMViz within <a href="http://www.eclipse.org" target="new">Eclipse</a>. You can also use <a href="http://www.eclipse.org" target="new">Eclipse</a> to create a jar file, which can be run outside of <a href="http://www.eclipse.org" target="new">Eclipse</a>. The process is:

  1. Choose menu command "Export..." and the select "Runable Jar File" in the "Java" section. Click "Next."
  2. Choose the NairnFEAMPMViz launch configution (such as the quot;NairnFEAMPMViz with Memory" one created above), choose export destination (which by default is (project)/lib/NairnFEAMPMViz.jar, where (project) is the name you gave this project in your workspace), and select to "Extract required libraries into generated JAR."
  3. Click "Finish" to generate the jar file

To run the jar with sufficient memory, navigate to the "lib" folder and run the NairnFEAMPMViz jar file created using:

java -Xmx512m -jar NairnFEAMPMViz.jar

The -Xmx512m argument is to give the virtual machine sufficent memory (as explained <a href="#runningViz">above</a>).

Retrieved from "http://osupdocs.forestry.oregonstate.edu/index.php?title=NairnFEAMPMViz&oldid=527"