Main Page

This documentation wiki is for the computational mechanics software from Oregon State University in the research group of Prof. John A. Nairn. This software package focuses on material point method (MPM) calculations (OSParticulas and NairnMPM), but also includes basic finite element analysis (FEA) calculations (NairnFEA). The user-interface tools for setting up and visualizing calculations are NairnFEAMPM (for Mac) and NairnFEAMPMViz (for Windows and Linux).

Getting Starting

Quick Start: If you using Windows, the best way to start is to download the NairnFEAMPMViz package for Windows. It has all you need to run and visualize calculations. You can run this package without downloading and compiling any code and without installing any third-party software tools. If you want to try more (or are not using Windows), see the next steps for obtaining, compiling, and running code and then visualizing the result.

The calculation engines for material point method (MPM) simulations are called OSParticulas and NairnMPM. The calculation engine for finite element analysis (FEA) is called NairnFEA. These are all object-oriented, C++, platform-independent code engines. The first steps to using these tools are:

Note that quick-trial packages with compiled binaries for code engines and libraries are available for Mac and Windows. Although you can run these with no additional downloads or compiling tasks, it is better to download the source code, build all needed tools, and use them to run calculations. The download/compile method is also essential for cases when the quick-trial versions do not run on your computer and to get the best versions of the code engines.

Input Files for Calculations

MPM simulations using OSParticulas or NairnMPM or FEA calculations using NairnFEA are controlled by input from an XML input file. This input file can be created manually by using any text or XML editing software. It is usually preferred, however, to use a higher-level scripting language to set up the calculations and then have an interpreter format those commands into the XML files needed by the code engines. This scripting method allows for more powerful input files that are much easier to customize for a range of simulations. Scripting calculations can be done by using either the NairnFEAMPM application (Mac only) or the NairnFEAMPMViz (Java tool) application. The scripting languages in these two applications are almost identical.

The bulk of the documentation in this wiki is involved with describing the features of the software and explaining the input commands needed to use those features. The features and input commands documentation for MPM or FEA calculations are in the following sections:

Input Files for MPM Calculations
Input Files for FEA Calculations

For convenience, these help topics are listed in the side bar on the left.

Scripted Input Files

The recommended method for writing input files is to use the built-in scripting commands. Scripted input files are comprised of a series of commands. This documentation will explain these commands and elements using the style:

 Command (arg1),(arg2),<(arg3)>,<(arg4)>

where

Command is the command name.
(arg1),(arg2), etc., specify arguments whose function will be explained along with the command. Arguments are separated by commas, spaces, or tabs. If an argument includes a space, enclose that argument in quotes.
<(arg3)> - enclosing an argument in angle brackets indicates an optional argument. If the argument is omitted, the code will assume some default value.

The main reason to prefer scripted files is their flexibility. Besides a series of command, these input files use a built-in scripting language that can make use of variables and both numeric and string expressions.

XML Input Files

If you are a glutton for punishment and do not mind absence of variables and expressions, input commands can be written directly in XML input files comprised of a series of XML elements. This documentation will explain all XML elements for all features using the style:

 <Command attr1='(arg1)' attr2='(arg2)'>(arg3)</Command>

where

Command is the XML element name.
(arg1),(arg2), etc., specify arguments whose function will be explained along with the command.
attr1, attr2, etc., are attributes to the XML element.

Visualization

Once you have created input files and run calculations, you will want to visualize and analyze the results. These tasks can be done by a variety of methods:

NairnFEAMPM - this application (which is the preferred choice, but Mac only) can do lots of visualization. For 3D it can visualize some results in particle plots only and time plots, but is more limited than some other 3D graphics tools.
NairnFEAMPMViz.exe - this Windows application can both run and visualize results and is available in a complete package that bundles exes and dlls (and Jave runtime environment if needed) to run NairnMPM, NairnFEA, and OSParticulas. It has many options for 2D visualization, but for 3D. it can only plot results version time. See below for 3D visualization options.
NairnFEAMPMViz.jar - this Java application (which is bundled into an executable for Window) alternatively can be run as a Java application in Linux, Mac, or Windows. It can run and visualize calculations. It has many options for 2D visualization, but for 3D. it can only plot results version time. See below for 3D visualization options.
ParaView or VisIt - these two free, multi-platform tools, can plot results archived as VTK files by using the VTKArchive Custom Task) or extracting particle data to VTK files using ExtractMPM. The custom task options get grid-based plots and particle extraction gets particle plots. It is possible these two types of VTK files could be read by other graphics tools as well. they use a common file format.
ExtractMPM - for even visualization options, you can use the ExtractMPM tool to extract selected data in various formats and input that data to any visualization tool you have available. This tool can extract data to plain text files, tab-delimited spread sheats, XML files, and VTK files. You can run ExtractMPM on a command line or by using the "Extract Particle VTKs..." command in NairnFEAMPM or in NairnFEAMPMViz

The visualization tools in the nairn-mpm-fea project (NairnFEAMPM, NairnFEAMPMViz, and ExtractMPM) automatically support all archive output file formats created by NairnMPM and NairnFEA and therefore can read them all. If you need even more customization, you can always write your own software tool to read output files and process the data however you want. To proceed along this task, you need to know the format of the output files:

Archive File Formats - this help topic documents the output files created by NairnMPM and NairnFEA.

Acknowledgments

This project is being developed as part of the author's research program. This program has been supported in the past by various organizations. Some specific acknowledgments go to:

Department of Agriculture (USDA)
- McIntire-Stennis account #229862, project #OREZ-WSE-849-U
- National Institute of Food and Agriculture (NIFA), #2013-34638-21483
- Forest Products Lab, #11-JV-11111129-137
- Cooperative Research, Education and Extension Service (CREES), #2006-35504-17444
National Science Foundation (NSF)
- CMMI 1161305
- Industry/University Cooperative Research Center for Wood Based Composites #IIP-1034975
- Mechanics of Materials program: CMS-9713356
- Mechanics of Materials program: CMS-940177
Small Business Grants
- Small Business Technology Transfer (STTR) contract with Eglin Air Base #FA8651-15-M-0298
Department of Energy (DOE)
- Nanotechnology Grant Subcontract 2103050
- Center for the Simulation of Accidental Fires and Explosions (C-SAFE), Lawrence Livermore National Laboratory, under Subcontract B341493