CAVS / Capabilities / Materials Modeling / ICME / Code Repository / MPC

Integrated Computational Materials Engineering (ICME)

MPC

What's New?

In MPCv4 (MEAM Parameter Calibration, ver.4), LAMMPS+MEAM is executed as a library inside the MATLAB workspace, not as an external process. MATLAB gateway functions (mexfunctions) execute LAMMPS library functions listed in src/library.h of the LAMMPS distribution. MATLAB functions carry out user-selected calculations for single elements, binaries, and ternaries.

In previous versions, LAMMPS+MEAM is separate process executed from a Python script to calculate energies, etc, and the Python script is invoked by MATLAB.

License

The MPCv4 license is File:License BSD 3 MSU.PDF

The source codes are available here.

The MATLAB scripts for the LAMMPS calculations and the gateway functions were written by Christopher D Barrett. The user interface was built by Ricolindo L Carino.

Sponsorship During 2015

Effort sponsored by the Engineer Research & Development Center under Cooperative Agreement number W912HZ-15-2-0004. The views and conclusions contained herein are those of the authors and should not be interpreted as necessarily representing the official policies or endorsements, either expressed or implied, of the Engineer Research & Development Center or the U.S. Government.

Publications

MPC is mentioned in Chapter 6 of Applications from Engineering with MATLAB Concepts - Case Studies in Using MATLAB to Build Model Calibration Tools for Multiscale Modeling

The MEAM parameter calibration tool: an explicit methodology for hierarchical bridging between ab initio and atomistic scales

Hierarchical Bridging Between Ab Initio and Atomistic Level Computations: Calibrating the Modified Embedded Atom Method (MEAM) Potential (Part A)

Hierarchical Bridging Between Ab Initio and Atomistic Level Computations: Sensitivity and Uncertainty Analysis for the Modified Embedded-Atom Method (MEAM) Potential (Part B)

Overview

MEAM Parameter Calibration (MPC) is a graphical MATLAB application for interactive editing of MEAM library and parameter files for single elements or alloys, and for semi-automated calibration of MEAM parameters to fit DFT and/or experimental data. Intended as a teaching tool, the MPC is designed to run on personal computers (Windows 7 64-bit, MacOS X Yosemite) without MATLAB. Video tutorials for use of the MPC tool can be found here, here, and here.

MPCv4 program

Features

  • LAMMPS+MEAM is executed as a library inside the MATLAB workspace, not as an external process.
  • Basic operations
    1. Load MEAM library file
    2. Select an element, or more if working with an alloy, from the MEAM library
    3. Specify primary, secondary 1, secondary 2 structures for an element or alloy component
    4. Load MEAM parameter file
    5. Edit library entries, parameter file entries
  • Operations on single elements
    1. Run one or more LAMMPS calculations for a single element
      1. Primary EV curve
      2. Secondary EV curve
      3. Secondary 2 EV curve
      4. Elastic Constants Calculation
      5. Vacancy Energy Calculation
      6. Interstitial Energy Calculations
      7. Surface Energy Calculations
      8. Generalized Stacking Fault Energy (GSFE) Calculations
      9. Generalized Interfacial (Twin) Fault Energy (GTFE) Calculations
    2. Plot results of single element calculations
  • Operations on binaries
    1. Specify one or more binary structures
    2. Run one or more LAMMPS calculations for one of more binaries
      1. Binary EV Curves
      2. Binary Elastic Constants Calculations
      3. Substitution Energy
      4. Interstitial Substitution Energy
    3. Plot results of binary calculations
  • Operations on ternaries
    1. Run binding energy calculation for a ternary
    2. Plot results of ternary calculations
  • Parametric study - investigate the effect of a single parameter on the results of LAMMPS calculations for a selected element, binary, or ternary
  • Calibration
    1. Specify calibration target data for each LAMMPS calculation enumerated above
    2. Select library file entries associated with elements as calibration parameters
    3. Select parameter file entries associated with elements, binaries and ternaries as calibration parameters
    4. Attempt to automatically fit the selected calibration parameters so that the results of the LAMMPS calculations will approach the calibration targets within specified tolerances
    5. Recall/redisplay results of attempted fits
  • Output operations
    1. Write MEAM library file, MEAM parameter file, MPCv4 restart file
    2. Write plot data to file
    3. Write file templates of calibration target data for single element, binary, ternary
    4. Write LAMMPS output log to file (log.lammps), or 'none'

Setup on Personal Computers Without MatLab

Windows 7, 64-bit

  • Download File:MPCv4 Win7 MATLAB R2016b Installer web.zip. Unzip to a temporary folder.
  • Run MPCv4_Win7_MATLAB_R2016b_Installer_web.exe in the temporary folder.
  • Specify C:\MPCv4 as the installation destination. As part of the installation process, the appropriate MATLAB Compiler Runtime will be downloaded automatically if it is not yet installed on the local system. Be prepared to wait for a long download time.
  • Run C:\MPCv4\application\MPCv4_Win7.exe
  • As a first time test of MPCv4, click menu item File | Load restart file, then select the file Al-MPCv4-restart.mat. The display should be similar to the figure above.

MacOS X (Yosemite) on Intel 64

  • Download File:MPCv4 OSX Installer web.zip. Unzip to a temporary folder.
  • Run MPCv4_OSX_Installer_web in the temporary folder.
  • Specify /Users/your_home_dir/MPCv4 as the installation destination. As part of the installation process, the appropriate MATLAB Compiler Runtime will be downloaded automatically if it is not yet installed on the local system. Be prepared to wait for a long download time. Take note of the installation directory for the MATLAB Runtime (for example, /Applications/MATLAB/MATLAB_Runtime/v85/) as it will be needed two steps below.
  • Open a command line window. Change directory to /Users/your_home_dir/MPCv4/application.
  • ./run_MPCv4_OSX.sh /Applications/MATLAB/MATLAB_Runtime/v85
  • As a first time test of MPCv4, click menu item File | Load restart file, then select the file Al-MPCv4-restart.mat. The display should be similar to the figure above.

Operations

Most actions in MPC are specified using point-and-click. The text display gives a summary of the effect of the most recent action.

In this document, bold refers to a label and italic refers to a menu (or context menu) item on the interface.

  1. Load MEAM library file
    2. The file library.meam from the LAMMPS distribution is automatically loaded upon start up if the file is found in C:\MPCv4. Select menu item File | MEAM library file to reload it or to load another library file.
  2. Select an element or the components of an alloy.
    1. Left-click LIBRARY popup to select an element. The library entries for the element will display, but are not editable (yet).
    2. Right-click LIBRARY popup then select Add ... to add as MEAM element
    3. Repeat steps 1 and 2 if working with an alloy
    4. To remove an element that was Add ...ed, select it as in step 1, then right-click as in step 2, but select Delete ...
    5. After selecting the desired element or alloy components, right-click LIBRARY popup, then select Fix .... This will fix the element or alloy components.
  3. Load a MEAM parameter file
    4. Select menu item File | MEAM parameter file to load (or reload) a MEAM parameter file. To start from scratch, load the file EMPTY.parameter.meam in C:\MPCv4
  4. Specify the Primary, Secondary 1, and Secondary 2 structures for the MEAM elements
    1. Left-click LIBRARY popup to select the element
    2. Right-click LIBRARY popup, then select Primary structure .... In the list dialog that appears, select a structure, then 'OK'.
    3. Repeat step 2 for the Secondary 1 and Secondary 2 structures
    4. If working with an alloy, repeat from step 1 for each MEAM element.
  5. Edit MEAM parameters
    • LIBRARY entries (if enabled), and non-indexed PARAMETERS entries (rc, delr, etc) may be edited directly.
    • For indexed PARAMETERS entries, select an element, a binary, or a ternary to display its associated parameter file entries. Then right-click the entry and select a possible action: Add ..., Edit ..., Delete ...
    • If a MEAM parameter is changed, the results of previous calculations (if any) are invalidated.
  6. Select LAMMPS calculations
    • Click menu item Plot | Select all results to mark as checked all calculations defined in MPC. This may require a significant running time for LAMMPS. Click on a result to toggle its check mark. Checked results will be included in LAMMPS runs.
    • Click menu item Plot | Include elements to toggle inclusion of single element calculations in LAMMPS runs.
    • Click menu item Plot | Include binaries to toggle inclusion of binary calculations in LAMMPS runs.
    • Click menu item Plot | Include ternaries to toggle inclusion of binary calculations in LAMMPS runs.
    • Single element or binary calculations that are not explicitly selected will be automatically included if these are prerequisites to other calculations.
    • Click menu item Plot | 1 plot or 2 plots (2x1) or 2 plots (1x2) or 4 plots (2x2) specify the number of plots to display.
    • To exclude an object from plots, first select the object using the LIBRARY popup, then right-click the LIBRARY popup and uncheck INCLUDE in DISPLAY of plots
  7. Run LAMMPS calculations
    • Click RUN LAMMPS Selected to run the checked calculations for the element/binary/ternary selected by the LIBRARY popup.
    • Click RUN LAMMPS Similar to run the checked calculations for the objects listed by RUN Similar= in the "Run, plot, calibration selections" text box (lower left section of interface). These objects are automatically determined based on the object selected by the LIBRARY popup.
    • Click RUN LAMMPS Included to run the checked calculations for the objects listed by RUN Included= in the "Run, plot, calibration selections" text box. To include an object, first select the object using the LIBRARY popup, then right-click the LIBRARY popup and choose INCLUDE in RUN CALCULATIONS
  8. Plot results
    1. Select the variable for the y-axis using the Y= popup.
    2. Select the variable for the x-axis using the X= popup.
    3. If two or more plots were specified (Plot | 2 plots or Plot | 4 plots), select the plot position using the subplot(...) popup.
  9. Parametric study (see section Parametric Study below)
  10. Calibrate MEAM parameters (see section Calibration below)
  11. Write to files
    • MEAM potential files: File | Write library and parameter files
    • MPCv4 restart data: File | Write restart file records the state of the MPC application. The application can be restored to this state by File | Load restart file
    • Plot data: if the menu item File | Write plot data to file is checked, then the plotted points will be written as comma-separated-values (CSV) to the 'plots' subdirectory. The file name is composed from the tag(s) for the computation (ex. E0, E1, H, Nx, C11, Substitution, H_vs_Nx) and the tag for the element or binary (ex. Al, Al+Mg).
    • Templates for calibration target data: File | Write calibration data template (must be checked; uncheck to cancel)
    • LAMMPS output log: File | Re-open LAMMPS, specify '-log' for Argument #1, and the file name for the Argument #2 (or 'none' to prevent creation of log)

Parametric Study

  1. Perform steps 1-8 of section Operations for the element or alloy components of interest. Initialize all parameter file entries that will be used for parametric study.
  2. Select the computations of interest via menu item Plots.
  3. Click RUN LAMMPS Selected or RUN LAMMPS Similar once if computations were checked that were unchecked previously.
  4. Right-click a label under LIBRARY or a popup under PARAMETER, then select Parametric study for that item.
  5. Enter range of values for that item and the number of values to be calculated. Use no more than 10 values, otherwise the waiting time for the calculations to complete will be very long.
  6. When the calculations are complete, a checkbox labeled Parametric will appear below RUN LAMMPS. Select the variable you want to display using the 'Y=' popup.
  7. Uncheck the Parametric checkbox to discard parametric calculations and quit.

Calibration

  1. Perform steps 1-8 of section Operations for the element or alloy components of interest. Initialize all parameter file entries that will be used as calibration parameters.
  2. Create templates for calibration targets as follows:
    1. Select menu item File | Write calibration data template and ensure that it is checked.
    2. Test-run all calculations with the initial MEAM library file and MEAM parameter file entries. Calibration data templates will be automatically created in the working directory.
    3. Uncheck menu item File | Write calibration data template.
  3. Edit+rename calibration data templates to specify actual calibration targets. Remove or comment out entries for which no calibration targets are available.
  4. Load calibration target data.
    1. Left-click LIBRARY popup to select an element, or a binary, or ternary with calibration data.
    2. Right-click LIBRARY popup, select LOAD calibration data file ..., then navigate to a calibration data file made in step 3. Alternatively, select ENTER calibration data ... to initiate a dialog for manual entry of data.
    3. Repeat steps 4.1 and 4.2 for each element/binary/ternary with available calibration data.
  5. Select MEAM parameters to calibrate (parameters associated with elements).
    1. Left-click LIBRARY popup to display an element for which a library file entry is a MEAM parameter to be calibrated.
    2. Right-click the label of the library file entry, and select Add to calibration parameter list. The entry should be included in the Parameters= {...} list in the "Run, plot, calibration selections".
    3. Repeat step 5.2 for each library file entry of the selected element that is be included in the Parameters= {...} list.
    4. For a parameter file entry associated with the element that is a MEAM parameter to be calibrated, right-click the entry and select Add to calibration parameter list.
    5. Repeat from step 5.1 for each element that has a library file entry be included in the Parameters= {...} list.
  6. Select MEAM parameters to calibrate (parameters associated with binaries/ternaries).
    1. Left-click LIBRARY popup to display binary/ternary for which a parameter file entry is a MEAM parameter to be calibrated.
    2. Right-click the parameter file entry, and select Add to calibration parameter list. The entry should be included in the Parameters= {...} list.
    3. Repeat step 6.2 for each parameter file entry of the selected binary/ternary that is be included in the Parameters= {...} list.
    4. Repeat from step 6.1 for each binary/ternary that has a parameter file entry be included in the Parameters= {...} list.
  7. Select calibration targets.
    1. Left-click LIBRARY popup to display an element, a binary, or a ternary with calibration data to be used as calibration target.
    2. Right-click PARAMETERS popup, select an unchecked Scalar: ... or Curve: .... If the latter, a dialog will accept inputs of the left and right indices of the data points in the curve to be used as calibration targets. If targeting the minimum in the curve, enter the suggested index of the minimum point (minus 1 or 2) for the left index and (plus 1 or 2) for the right index. The selected target should be included in the Targets= {...} list below the text display area.
    3. Repeat from step 7.1 for each element, binary, ternary with calibration data be included in the Targets= {...} list.
  8. Remove calibration targets and/or parameters.
    1. To remove a library file entry, left-click LIBRARY popup to select the element. Right-click the label of the library file entry, then select Remove from calibration parameter list.
    2. To remove a parameter file entry, left-click LIBRARY popup to select the element/binary/ternary. Right-click the parameter file entry, then select Remove from calibration parameter list.
    3. To clear the Parameters= {...} and Targets= {...} lists, right-click Calibration label and select Clear calibration targets and parameters.
  9. Click Calibration Run button. Wait a few minutes/hours. If bored, click 'Stop'. Try again from step 5.
  10. Click Calibration History popup to redisplay attempted fits. Right-click popup to select attempted fits to delete.

Build LAMMPS+MEAM for MPCv4 on Linux with MATLAB R2017b and gcc-4.9.3

(See README-MPC.TXT in the source distribution package)

Build LAMMPS+MEAM for MPC on Windows 7 with MATLAB R2015b

MATLAB R2015b includes TDM-GCC-64 gcc/g++ compilers (gcc 4.9.2) but not gfortran for compiling the MEAM library. Here are the instructions to build LAMMPS+MEAM for MATLAB R2015b: File:LAMMPS TDM-GCC-64 Win7 MATLAB R2015b Gnumex.txt.

To build LAMMPS+MEAM for MATLAB R2013b or R2014a, use these instructions: File:LAMMPS MinGW64 Win7 MATLAB R2013b Gnumex.txt

Build LAMMPS+MEAM for MPC on MacOSX (Yosemite)

The following instructions worked on this platform:

- MacBook Pro + Yosemite (Thanks to Mike Baskes)
- MATLAB R2015a
- XCode 6.0.1
- gfortan, from Macports-2.3.4 + port gcc43 (https://www.macports.org/)
- link /opt/local/bin/gfortran-mp-4.3 to /usr/bin/gfortran
- link /opt/local/bin/gcc-mp-4.3 to /usr/bin/gcc
- link /opt/local/bin/g++-mp-4.3 to /usr/bin/g++
- LAMMPS, in ~/Downloads/lammps-10Aug15 (referred to as <lammps_dir> below)
- Makefiles:
  + copy file File:Makefile.txt to <lammps_dir>/src/STUBS/Makefile
  + copy file File:Makefile.gfortran.txt to <lammps_dir>/lib/meam/Makefile.gfortran
  + copy file File:Makefile.mac.txt to <lammps_dir>/src/MAKE/MACHINES/Makefile.mac

  1. Compile LAMMPS
    1. MEAM
      2. $ cd <lammps_dir>/lib/meam/
$ make -f Makefile.gfortran
    2. MPI stubs
      3. $ cd <lammps_dir>/src/STUBS
$ make
    3. LAMMPS executable
      4. $ cd <lammps_dir>/src
$ make clean-mac
$ make yes-meam
$ make mac
    4. LAMMPS static library
      5. $ cd <lammps_dir>/src
$ make mode=lib mac
    5. Test the LAMMPS executable
      6. $ cd <lammps_dir>/examples/meam
$ ../../src/lmp_mac > in.meam
  2. Compile mexfiles
    1. Change to private directory (where the mexfunctions are located)
      2. $ cd ~/Documents/MATLAB/MPCv4-OSX/private/
    2. Copy static libraries
      3. $ cp <lammps_dir>/src/STUBS/libmpi_stubs.a .
$ cp <lammps_dir>/lib/meam/libmeam.a .
$ cp <lammps_dir>/src/liblammps_mac.a liblammps.a
    3. Start 'text-only' MATLAB
      4. $ /Applications/MATLAB_R2015a.app/bin/matlab -nodisplay -nojvm
    4. Generate mexfiles
      5. >> lammps_setup_MacBook
    5. Test run
      6. >> clear all; test_run_lammps_MPC