LSMDD (Level Set Method Dislocation Dynamics) library provides support for the serial and parallel simulation of dislocation motion and interactions in materials. The library consists of a collection of Fortran subroutines, C functions, and C++ classes for managing the level set functions used to represent dislocation lines and simulating dislocation physics.
The numerical algorithms underlying the LSMDD were originally developed by Xiang et. al. in their series of papers on level set method approaches for simulating dislocation dynamics. However, because there are still open research questions about how various aspects of dislocation motion and interactions, the LSMDD library has been designed to allow flexibility in how the physics of dislocations are computationally modeled.
The main features of the library include:
The parallel level set method calculations required by the LSMDD are provided by the Level Level Method Library (LSMLIB) being developed in the Mechanical & Aerospace Engineering Department at Princeton University and the Structured Adaptive Mesh Refinement Application Infrastructure (SAMRAI) developed and maintained in the Center for Applied Scientific Computing (CASC) at Lawrence Livermore National Laboratory (LLNL). We have leveraged the vector level set method calculations and standard level set method discretizations provided by LSMLIB. The parallel and restart capabilities of LSMDD are provided by SAMRAI. It is worth mentioning that the LSMLIB also relies heavily on SAMRAI for its parallel and restart capabilities.
We made the decision to leverage these libraries because they are designed to address several key issues:
This library is still under development and has not been thoroughly tested. If you find a bug, please send me a bug report at ktchu@princeton.edu, and I will make an attempt to fix it in the next release of the library. Thank you for your patience during the development process.
Users of LSMDD should be comfortable using C++ and object-oriented programming. In addition, users should have familiarity with basic SAMRAI objects (e.g. CellData, Box, IntVector, etc.).
LSMDD is designed to be relatively straightforward to use while providing the flexibility to allow exploration of new dislocation phenomena. The basic steps required to implement a dislocation dynamics simulation based on LSMDD are as follows:
Several sample programs are provided in the examples directory. It is recommended that users refer to these programs when getting started with the LSMDD library.
The LSMDD library contains several C++ classes. These are designed to provide the user with access to high-level algorithmic components and shield them from low-level programming details of parallel dislocation dynamics computations.
The following is a list of the classes, utility functions, and data types that most users should be familiar with:
The DislocationDynamicsModule class orchestrates the stages of the dislocation dynamics simulation. The LSMDD_PhysicsStrategy class is an abstact base class for which the user must supply an implementation. This class defines the interface for initializing the level set functions for dislocation lines, computing forces on dislocation lines, computing velocities on dislocation lines, etc. The LSMDD_Parameters class stores various physical and algorithm parameters used by in LSMDD simulations. The BurgersVector class is a simple class that represents a Burgers vector. The PeriodicDislocationArrayElasticStressModule provides support for computing the stress field for periodic arrays of dislocation lines. The LSMDD_Utilities.h file defines several utility functions and macros that are helpful when computing forces and velocities on dislocation line segments. The InitializationModule class provides support for initializing the level set functions for a few common dislocation configuration. The BasicDislocationPhysicsModule, RestrictedSlipPlaneModule, and DislocationReactionModule classes provide routines for calculating the forces and velocities on dislocations using various aspects of dislocation physics. Finally, the LSMDD::STRESS_COMPONENT_TYPE (which is defined in LSMDD_Types.h) is an enumerated type that is used to identify components of stress within calculations in the LSMDD library.
The LSMDD library has been designed to allow users to supply implementations for general configurations of dislocation lines (other than periodic arrays). For these problems, the user must provide a concrete subclass of the ElasticStressStrategy class.
Currently, visualization of the results produced by LSMDD simulations is provided in the form of a few MATLAB scripts that plot dislocation lines using the output generated by LSMDD. These MATLAB scripts are located in the src/visualization directory.
In the future, we have plans to improve the visualization capabilities of LSMDD.
The top-level directory contains the following:
README.txt refers users to this web page. INSTALL.txt describes the installation procedure for the library. CHANGE_LOG.txt contains a list of the major changes to the library at each release. LICENSE contains the license for the LSMDD library. configure is a shell script (automatically generated by autoconf) that configures the build based on your system configuration. The config directory contains configuration files for building the LSMDD library. The doc directory contains documentation on how to use the library. The src directory contains the source code for the library. The external_libraries directory contains the source code and Makefiles for Steve Plimpton's parallel FFT library. The examples directory contains a few example codes that demonstrate the basic usage of the LSMDD library and may be used to test functionality of the library. Finally, the TO_DO.txt, configure.ac and Makefile.in files are files that only developers of LSMDD need to be aware of -- they may be safely ignored by users of the library.
In addition to these files and directories, two additional directories are added to the top-level directory after the build process: include and lib. These directories contain the header files and library archives for the LSMDD library.
The LSMDD library depends on the LSMLIB, SAMRAI, MPI (required for parallel calculations), and HDF5 (required for restart and visualization).
In addition, the elastic stress module example program depends on the SAMRAI Rapid Development Kit. The SAMRAI Rapid Development Kit is NOT a strict dependency of the LSMDD library.
This software library was supported in part by the National Science Foundation and the Air Force Office of Scientific Research.