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 want to enhance the source code to create new visualization options.

Introduction

The nairn-mpm-fea project includes a Java application called NairnFEAMPMViz that lets you create input files, run calculations, and visualize results for both NairnMPM and NairnFEA. On this page, you can download a complete package for Windows that includes everything needed to start running calculations without any additional installations. Once a package is downloaded, launch the application by described platform-dependent method. Instructions for using NairnFEAMPMViz are included in the its help window. This page also has some quick-start suggestions.

If you want to make changes to the NairnFEAMPMViz Java application, its entire source is included in the nairn-mpm-fea project. See the instructions on compiling NairnFEAMPMViz to learn how to create a new jar file from altered source code.

NairnFEAMPMViz Packages

The following downloads provide packages that contain the NairnFEAMPMViz application. They are full-featured versions of NairnFEAMPMViz and the download folder contains compiled binaries for finite element analysis and for material point method analysis along with libraries needed to run the application.

NairnFEAMPM Download	Size (MB)	Updated
NairnFEAMPMViz 11.0 for Windows - A complete package for use on Windows computers. This package contains all the needed exe and dll files to run calculations. It also contains a Java run time environment (which is the reason for the large size); use next download instead if you have Java installed on your computer	44.0	21 OCT 2023
NairnFEAMPMViz 11.0 for Windows - Same as the previous download except it omits the Java run time environment. It requires the Windows PC to be used to have compatible installation of Java version 1.8.0 or newer.	1.8	21 OCT 2023
Mac download removed due to MacOS-depedent C++ library issues. Use the NairnFEAMPMViz.jar file in the NairnFEAMPM download instead and you will need compile your own binaries.
No Linux package it provided. See below for running remotely on a Linux server.

If the above packages do not work, you can build your own java app, binaries, and libraries by checking out the nairn-mpm-fea project and compiling the source code to the NairnFEAMPMViz java app.

Running in Windows

Start NairnFEAMPMViz by double clicking the NairnFEAMPMViz.exe application in the downloaded folder. This application must remain in the same folder as the provided "Resources" folder. For convenience, the recommended installation is to move the expanded "NairnFEAMPMViz" folder to the standard Windows "Program Files" folder. If desired, you can create a short cut to the NairnFEAMPM.exe application in the folder and place that short cut on your desktop.

Running in MacOS

The preferred approach in MacOS is to download and use the NairnFEAMPM application. If you need to use a NairnFEAMPMViz.jar, you will first have to check out and compile the source code (including the xerces library). Once that is down, start the Java application provided in the download as a jar file by opening the Terminal app and use the command

java -Xmx512m -jar NairnFEAMPMViz.jar

The -Xmx option allocates the desired memory (where "m" means in megabytes). The command runs with 512 MB of memory. You can alter it to change this amount if needed. The Terminal window that will stay open while NairnFEAMPMViz is running. That window is also a console for the Java app and will display some messages that might provide useful information.

The first time you run NairnFEAMPMViz, you have to configure it to use the binaries you compiled. This configuration is done in the "Code" pane of the app preferences.

Note that double clicking the jar file will open it differently and may not allocate enough memory for large calculations, It might even block you from opening any files. The latter is Apple's way of telling you that you are not smart enough to run jar files that open other files. Launching as above might fix the problem. To use double clicking (with this or any other jar files), you have to change security and preferences for the Mac Java Launcher app. Apparently, if you know these secret steps, Apple will think you are smart enough to run jar files:

1. Open System preferences and click on the "Security and Preferences" panel.
2. Click the "Privacy" tab, choose "Full Disk Access", and click lock to enable changes.
3. Click the + icon and add /System/Library/CoreServices/Jar Launcher.app.

Running on a Linux Server

As a java app, NairnFEAMPMViz works fine in Linux, but no stand-alone package is currently provided. When using Linux, you will have to check out the nairn-mpm-fea project and build all needed code engines and libraries. Once they are created, you have to log onto the Linux server using X11 terminal software and enable "trusted X11 forwarding." The command line to connect is

ssh -Y -l username servername

or

 ssh -Y username@servername

Once connected, start NairnFEAMPMViz.jar application provided in the checkout by using the java command line:

java -Xmx512m -jar (path/to/NairnFEAMPMViz.jar)

and NairnFEAMPMViz will run in a graphical user interface. The -Xmx512m argument runs the jar file with 512 MB of memory. You can run with more or less if desired. For instructions on using NairnFEAMPMViz, including how to tell it where you saved the code engines, use the "Help" menu command in the application.

To use this method to connect from a Mac or a Windows PC, you will need a terminal application that supports X11 connections. A good choice for Macs is XQuartz. A good choice for Windows is MobaXterm (this app has free and paid versions, but free version should be enough). If running while directly connected to a Linux box, hopefully your installation will have some built-in X11 connection method to allow running of NairnFEAMPMViz in a graphical interface.

Using NairnFEAMPMViz

The first time NairnFEAMPMViz is run, you may need to do some setup (as explained in the help). Once set up, a quick-start explanation about typical use is as follows:

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. To try out a commands file immediately, you can open one of the sample files in "Examples" submenu. Save the example file and the proceed to the next step.
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.

One limitation of the NairnFEAMPMViz pacakages is that the embedded binaries may not be the latest versions from the nairn-mpm-fea project. Furthermore, the packaged MacOS code engines can only run in serial (due to Apple limitations for distributing software with OpenMP support). To use the latest versions of the code and enable parallel calculation on Mac while using the packages, you should:

1. Download Source Code (i.e., check out the nairn-mpm-fea project).
2. Compile the Code Engines for NairnMPM and NairnFEA.
3. Either copy the compiled binaries into the package folders (replacing the original versions) or configure NairnFEAMPMViz to run the code engines created by the project tools. See NairnFEAMPMViz's help window for information on configuring it to run new code engines.

Compiling the NairnFEAMPMViz Java Application

The nairn-mpm-fea project contains the complete source code for NairnFEAMPMViz. One option for creating new visualization tools, therefore, 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 (IDE) for Java (and for other languages). 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, possibly with minor modifications.

Assuming you have the Eclipse IDE for Java development installed, 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. A "NairnFEAMPMViz" project should show up.
4. You can select "Copy projects into workspace" or leave it unchecked. When checked, all files are copied to your Eclipse workspace and the files in the code check out remain in place. If not checked, the Eclipse project will directly use (and edit) the files in your check out.
5. Click "Finish" to import the project.

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. If desired, you can save the jar file to a downloaded package to update that package to use your recompiled jar file.

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 follows:

1. Install tools for subversion (this step and the next). Choose "Install New Software..." menu command (in the "Help" menu) choose download site to "work with." Once site data are loaded, choose "Subversive SVN Team Provider" in the "Collaboration" section and proceed to installation. Note that the group developing the SVN plug in dropped out of Eclipse Project after version Eclipse Oxygene. To install the SVN tools after this version, you have to adding the mirror site http://download.eclipse.org/technology/subversive/4.0/update-site/ (this approached works through Eclipse 2021-06. Future version might need to update this link such as to change "4.0" to latest version. To check for new options, look for "Directory Contents" at http://download.eclipse.org/technology/subversive/). After installation, restart Eclipse.
2. Use of subversion also needs a "connector," which can be done using Eclipse→Preferences→Version Control (Team)→SVN and opening the connectors tab. You should then "Get Connectors..." and select the one you want. Select a connector that is compatible with your version of subversion (to check your version, use "svn --version" in your command-line tool). After installation, restart Eclipse. If no connectors show up, you can try to manually install them using the "Install New Software..." command and adding the site https://community.polarion.com/projects/subversive/download/eclipse/6.0/update-site/.

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/trunk/Visualization/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

Warning: This compile method is not routinely checked. It may be out of sync with current version of the code.

You can alternatively 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.7.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).