NairnFEAMPMViz

NairnFEAMPMViz is a Java application to create simulations, run them, and visualize them. This page has brief instruction on its use and on compiling it if you need to change the source code.

Introduction

The nairn-mpm-fea project includes source code for a Java application called NairnFEAMPMViz that lets you create input files, run calculations, and visualize results for both NairnMPM and NairnFEA. The nairn-mpm-fea checkout also has a NairnFEAMPMViz.jar file for this application that is ready to run. Note that NairnFEAMPMViz requires a system with Java 1.7.0 (a.k.a Java 7) or newer installed.

If you want to make changes to the code, you will need to see the instruction on compiling NairnFEAMPMViz to learn how to create a new jar file from the altered source code.

Running NairnFEAMPMViz

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 jar file).

When running in Windows, you can launch from a Windows command prompt and 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.7.0_80\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.

Creating a Windows Shortcut to NairnFEAMPMViz

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

• Copy the file Visualization/build/NairnFEAMPMVIz.bat to the folder containing the jar file you want to run. This file contains:

  java -Xmx512m -jar NairnFEAMPMViz.jar
  

  The batch file line assumes your Windows environment includes the path to the java command. If not, you can replace java by the full path to the java executable. The -Xmx512m set the amount of memory used to run NairnFEAMPMViz.jar in MB. You can decrease or increase as needed.
• Next create a short cut to the moved batch file (and give it any desired name). Right click on the new shortcut and select "Properties". In the properties window:
  1. Make sure "Target" and "Start in" refer to the batch file, it's folder, and the NairnFEAMPMViz.jar file is in that folder too.
  2. Choose "Minimized" from the "Run:" menu.
  3. Click "Change Icon..." and "Browse..." for the NairnFEAMPMViz.ico file (in the 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 and with the desired amount of available memory. If you ever run out of memory for large calculation visualization, edit the batch file and increase the number in the -Xmx argument.

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.

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.

NairnFEAMPMViz Setup

The first time you run NairnFEAMPMViz, it will assume that the NairnFEA and NairnMPM code engines are in a special "bundle" folder that is located in the same folder as the NairnFEAMPMViz.jar file. You can run with these setting by creating that folder and moving NairnFEA and NairnMPM code engines to that folder. Alternatively, you can tell NairnFEAMPMViz a different location for the NairnFEA and NairnMPM code engines and of a Unix shell. The steps are

1. Choose "Preferences..." menu command or click the "Prefs" icon
2. Click the "Code" tab
3. Click the first four "Change..." buttons and locate the NairnMPM (or OSParticulas if you are using it) executable, the NairnMPM.dtd file, the NairnFEA executable, and the NairnFEA.dtd file (note that in Windows, you must put a copy of xerces-c_3_1.dll (numbers may vary) in the same folders as the selected code binaries).
4. The bash shell command usage depends on system being used. The default setting is $(windows) which assumes the code will run using a DOS command line and that the code engines were compiled using Visual Studio. In Mac or Linux, the bash shell is usually at /bin/bash, but the shell is only needed when running jobs in background. If using cygwin in Windows (which is no longer recommended), the bash.exe command will be in the bin folder of the root cygwin or cygwin64 folder.
5. Optionally click the last "Change..." button and select a work space directory. When a directory is selected, NairnFEAMPMViz will default to this directory when opening and saving files.

To do a test calculation, choose the "File → New FEA Commands" or File → New MPM Commands" menu commands (or click their icons). These will open a file with sample scripted input commands. Save the new commands to a new file with extension .fmcmd and the calculations. When the calculations are done, the results file will open for visualization.

If nothing happens when running in Windows, you probably do not have the xerces-c_3_4.dll file available (and unfortunately a missing dll does not send an error message to the java app that launched the command). You need to put a copy of xerces-c_3_1.dll (numbers may vary) in the same folder as the NairnFEA.exe and NairnMPM.exe file you selected in step 3 above. For running on a different computer, it is better to use a special "bundle" folder and it will need some additional dlls.

Special "bundle" Folder

To make code engines for calculations more portable to different computers, the NairnFEAMPMViz app looks for a special folder called "bundle" located in the same folder as the NairnFEAMPMViz.jar file. The folder should contain:

1. NairnFEA and NairnMPM code binaries (or NairnFEA.exe and NairnMPM.exe in Windows).
2. NairnFEA.dtd and NairnMPM.dtd files to allow validation of input XML files.
3. On windows, the folder must contain the xerces-c_3_1.dll (numbers may change depending on xerces version).
4. If you will run calculations on a separate Windows computer that does not have Visual Studio installed, you must additionally add vcruntime140.dll, msvcp140.dll, and vcomp140.dll to the folder. These can be found in you Visual Studio installation computer (they are redistributable libraries).

You can now copy a folder containing NairnFEAMPMViz.jar file and this special "bundle" folder to another computer and run calculations without needing to checkout and compile all code on that computer. of course, the other computer must be compatible with the code (e.g., engines compiled for that platform and have Java 7 or new installed).

NairnFEAMPMViz Usage

The use of NairnFEAMPMViz follows these general tasks:

1. You can create "New" input commands files (or open saved ones with "Open" command or by clicking the "Folder" icon) and edit them in a text editing window.
2. To run an analysis, choose the "Analyze → Run FEA/MPM Analysis" command (or click the run arrow icon). You will asked to decide where to save the results (as an .fea or .mpm file). Once you select a name, the calculations will run.
3. When the calculations are done, the results file will open for visualization. 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.
   • 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.
   • 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").
4. 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 NairnMPM or NairnFEA to standard output, and not one of the associated files written by those calculations. Once opened, the text results will appear as described above after running calculations.
5. For more details on use of NairnFEAMPM, click the "Help" button in the application.

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.

Compiling Using Eclipse

Eclipse 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 NairnFEAMPMViz code into an Eclipse project. This method was done using Eclipse Mars (4.5), which is available free for Windows, Mac, and other platforms. These steps will probably work for other versions too, possible with minor modifications.

Assuming you have Eclipse installed (and set up for Java development), you can import a project for editing NairnFEAMPMViz as follows:

1. Start Eclipse
2. Choose Import... menu command and select "Existing Projects into Workspace" in the "General" section.
3. On next screen, choose Visualization/src folder in the cloned nairn-mpm-fea project.
4. The "NairnFEAMPMViz" project should show up. Select it and then finish the import (you can copy files to you Eclipse work space or leave them in the project checkout).

The imported project should compile fine. 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 let you compile and run NairnFEAMPMViz within Eclipse. You can also use Eclipse to create a jar file, which can be run outside of Eclipse. The process is:

1. Choose menu command "Export..." and then select "Runable Jar File" in the "Java" section. Click "Next".
2. Choose the NairnFEAMPMViz launch configuration (such as the "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.
4. See above to run the new jar with sufficient memory.

Compiling a Checked Out Copy - OSParticulas Only

When using OSPartculas, you can alternatively check out the NairnFEAMPMViz code directly from the repository using SVN. These steps need tools for subversion installed in Eclipse as described here. Be sure to do the optional step for Java development (or just download Eclipse for Java development). You are now ready to manage Eclipse projects using SVN. To get started 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":
   • URL: http://(OSParticulas Server)/svn/OSParticulas/trunkVisualization/src
   • User: enter your username and password for the OSParticulas svn repository.
3. Choose "Head Revision" for latest version or use date or revision options for older versions and then click "Next" (or "Finish" is "Next" is not available).
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. See above for how create a running option with sufficient memory.

The above process will create a project in your Eclipse 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..." (be sure to enter message described the changes being committed).

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.6.0 or newer. It is available free on various platforms 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