MaterialSim Grain Growth

MaterialSim Grain Growth preview image

2 collaborators

Uri_dolphin3 Uri Wilensky (Author)
Default-person Paulo Blikstein (Author)


(This model has yet to be categorized with any tags)
Model group CCL | Visible to everyone | Changeable by group members (CCL)
Model was written in NetLogo 5.0.4 • Viewed 267 times • Downloaded 20 times • Run 1 time
Download the 'MaterialSim Grain Growth' modelDownload this modelEmbed this model

Do you have questions or comments about this model? Ask them here! (You'll first need to log in.)


Most materials are not continuous arrangements of atoms. Rather, they are composed of thousands or millions of microscopic crystals, known as grains. This model shows how the configuration and sizes of these grains change over time. Grain size is a very important characteristic for evaluating the mechanical properties of materials; it is exhaustively studied in metallurgy and materials science.

Usually this kind of study is made by careful analysis and comparison of pictures taken in microscopes, sometimes with the help of image analysis software. Recently, as the processing power of computers has increased, a new and promising approach has been made possible: computer simulation of grain growth.

Anderson, Srolovitz et al. proposed the most widely known and employed theory for computer modeling and simulation of grain growth, using the Monte Carlo method. Instead of considering the grains as spheres, and being obliged to make numerous geometrical approximations, Anderson proposed that the computer would simulate the behavior of each individual atom in the system. Each atom would follow a very simple rule: it will always try to have, in its immediate neighborhood, as many atoms as possible with the same orientation as it. It will do so by randomly (hence Monte Carlo) re-orienting itself and seeing if it is more stable than it was before. If it is, it will stay in its new orientation, and if not, it will revert back to its previous orientation.

This model is part of the MaterialSim (Blikstein & Wilensky, 2004) curricular package. To learn more about MaterialSim, see


The basic algorithm of the simulation is simple: each atom continuously tries to be as stable as possible. Its stability is based on the number of neighbors with similar orientations: the more similar neighbors, the more stable it is. If it has only few similar neighbors, it will try to relocate to a more stable position. The steps for each tick in the model are:

1. Choose a random atom.

2. Ask that atom to calculate its present energy (based on its stability). The atom does this by counting how many similar neighbors it has.

3. The atom then chooses at random one of its neighbors, and orients itself in the same direction as that neighbor.

4. The same atom then calculates its energy, based on this new, tentative orientation.

5. Finally the atom compares the energy levels in each of the two states: the lowest value "wins", i.e., the more similar neighbors, the more stable the atom is.

6. Repeat steps 1-6.

The **annealing-temperature** slider controls the probability of maintaining a reorientation that yields less stability. The **percent-element2** slider defines the percentage of second-phase particles to be created when the user setups the simulation. Those particles are not movable and are not subject to grain growth. Atoms with element2-particles as neighbors will see them as dissimilar.

Note that the actual number of atoms is small compared to a real metal sample. Also, real materials are three-dimensional, while this model is 2D.


### (1) Simulation starting point.

**starting-point**: You can start from a random arrangement or a picture from a microscope. File formats accepted are: `.jpg`, `.png`, `.bmp`, and `.gif`. The image will be automatically resized to fit into the world, but maintaining its original aspect ratio. Note that the image MUST HAVE THE SAME ASPECT RATIO AS THE WORLD. In other words, if the world is square, the image should be square as well. Prior to importing the image, it is recommended to clean it up using an image editing software (increase contrast, remove noise). Try to experiment various combinations of values for the view's size and the patch size to get the best results

**percent-element2**: You can also determine if you want a certain percentage of a second element, sometimes called grain refiner.

**setup**: Sets up the model as indicated.

### (2) Change the shape of atoms.

Different shapes might help visualize the atomic planes, or the proportion of different types of grains.

**atom-shape**: Choose which shape you want.

**apply-shape**: Re-draws all the atoms with the shape you chose.

### (3) Draw/edit grains (optional)

You can use this to "draw" new grain structures, or edit the grains at any point during the simulation.

**draw**: When this button is pressed down, you can change the color (orientation) of atoms in the model.

**brush-size**: This determines how many atoms’ orientation you change at a time.

**erase-all**: This changes the orientation of all atoms.

**draw-color**: Here you can change the color (and orientation) that that you change atoms to, when you draw on them.

### (4) Run Model.

You can choose to have the model keep repeating the steps (as described above) or to run just one tick. Running just one tick will allow you to see more clearly what happens over time.

**annealing-temperature**: changes the probability of non-favorable orientation flips to happen. A 10% value, for instance, means that 10% of non-favorable flips will be maintained. This mimics the effect of higher temperatures.

### Grain size plot and calculations

**ticks-per-measurement **: to increase the model's speed, the user can choose not to calculate grain size at every time step. If grain size is calculated at every ten time units (20, 30, 40 etc.), the performance is slightly increased. This only affects the plot and the monitors, but not the actual simulation.

**measure grains now**: if the user feels there is too much time between each grain measurement, and wants to calculate it immediately, this button can be used.

### Plots and monitors

**Grain Size (log-log)**: Grain size vs. time, in a log-log scale. Under normal conditions (**annealing-temperature** = 0 and **percent-element2** = 0), this plot should be a straight line with an angular coefficient of approximately 0.5.

**Grain Size**: grain size

**Log Time**: log of ticks in the simulation so far

**Log Grain Size**: Log of the grain size

**growth-exponent**: the angular coefficient of the **Grain Size (log-log)** plot. This number should approach 0.5 with **annealing-temperature** = 0 and **percent-element2** = 0.


When you setup with a random orientation and run the simulation, notice that the speed of growth decreases with time. Toward the end of the simulation, you might see just two or three grains that fight with each other for along time. One will eventually prevail, but this logarithmic decrease of speed is an important characteristic of grain growth. That is why the **Grain Size (log-log) plot is a straight line in a "log-log" scale.

Notice also that if you draw two grains, one concave and one convex, their boundary will tend to be a straight line, if you let the simulation run long enough. Every curved boundary is unstable because many atoms at its interface will have more different than equal neighbors.


Increase the value of the **annealing-temperature** slider. What happens to the **Grain Size (log-log)** plot, and to the boundaries' shapes?

Try to increase the **percent-element2** slider to 5%. Then choose “random arrangement” and click **setup**, and **go**. What happens to grain growth? Now try several values (1, 3, 5, 7, 9%), for instance. What happens with the final grain size? What about the **Grain Size (log-log) plot and the **Growth Exponent**?

One advanced use of this model would be to get a digital picture of a real metallic sample, reduce noise and increase contrast with image editing programs, and load into this model using the **Import Image** feature in the starting-point chooser. Don't forget to update the width and height of the view's size to accommodate the picture, and also to change the patch size in order to be able to see the whole sample.


This model assumes that the misorientation between two grains has no effect on their growth rates. Two grains with a very similar crystallographic orientation have the same growth rate as grains whose orientations differ by a lot. Try to take the angular misorientation into consideration.

When we insert second-phase particles, all of them have the same size. Try to create a slider that changes the size of these particles.


Rather than containing all of the code that updates variables used for plotting, the **Grain Size (log-log)** plot calls a procedure that does this. The reason is that there is quite a lot of code, and it would be difficult to work with inside the plot. Notice also that this code updates the global variables shown in the monitors to the right of the plot.

The model uses a hexagonal grid as opposed to the usual, square one. It also uses different shapes for different visualization purposes. Finally, it uses the `import-pcolors` primitive for image import.


Crystallization Basic

Crystallization Directed

Crystallization Moving


This model is part of the MaterialSim (Blikstein & Wilensky, 2004) curricular package. To learn more about MaterialSim, see

Two papers describing the use of this model in education are:

Blikstein, P. & Wilensky, U. (2005) Less is More: Agent-Based Simulation as a Powerful Learning Tool in Materials Science. The IV International Conference on Autonomous Agents and Multiagent Systems. Utrecht, Netherlands.

Blikstein, P. & Wilensky, U. (2004) MaterialSim: An agent-based simulation toolkit for Materials Science learning. (PDF, 1.5 MB) Proceedings of the International Conference on Engineering Education. Gainesville, Florida.

The core algorithm of the model was developed at the University of Sao Paulo and published in: Blikstein, P. and Tschiptschin, A. P. Monte Carlo simulation of grain growth (II). Materials Research, Sao Carlos, 2 (3), p. 133-138, jul. 1999.

Available for download at: See also for more information (in Portuguese).


If you mention this model in a publication, we ask that you include these citations for the model itself and for the NetLogo software:

* Blikstein, P. and Wilensky, U. (2005). NetLogo MaterialSim Grain Growth model. Center for Connected Learning and Computer-Based Modeling, Northwestern Institute on Complex Systems, Northwestern University, Evanston, IL.

* Wilensky, U. (1999). NetLogo. Center for Connected Learning and Computer-Based Modeling, Northwestern Institute on Complex Systems, Northwestern University, Evanston, IL.


Copyright 2005 Uri Wilensky.

![CC BY-NC-SA 3.0](

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 License. To view a copy of this license, visit or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Commercial licenses are also available. To inquire about commercial licenses, please contact Uri Wilensky at

Comments and Questions

Please start the discussion about this model! (You'll first need to log in.)

Click to Run Model

;; two different materials or phases
breed [ element1s element1 ]  ;; element1 is the main material
breed [ element2s element1 ]  ;; element2 is the materials which is
                              ;; dispersed inside element1 (second-phase particles)

element1s-own [
  neighbors-6   ;; agentset of 6 neighboring cells

turtles-own [
  neighboring-turtles  ;; agentset of surrounding atoms
  sides-exposed        ;; number of sides exposed to walls  (between 0 and 4)

globals [
  logtime                          ;; log of time
  colors                           ;; used both to color turtles, and for histogram
  xmax                             ;; max x size
  ymax                             ;; max y size
  average-grain-size               ;; average grain size
  logaverage-grain-size            ;; log of average grain size (for plotting)
  initial-loggrain-size            ;; For grain growth exponent calculation and graphing
  initial-logtime                  ;; For grain growth exponent calculation and graphing
  grain-growth-exponent            ;; Grain growth exponent
  update-plots?                    ;; boolean for updating plots immediately

;; setup checks whether user has chosen "import image" or random in the chooser-widget

to setup
  if starting-point = "Random Arrangement" [
  if starting-point = "Import Image" [

to setup-hex-grid
  ;; setup the hexagonal grid in which atoms will be placed
  ;; and creates turtles
  set-default-shape element2s "square 2"
  ask patches [
    sprout 1 [
      ;; if there is a second element, create the corresponding atoms
      ifelse (percent-element2 > random 100) [
        ;; element2 is the fixed second-phase particle
        set breed element2s
        set color white
        set heading 360
        ;; element1 is the main material which grows grains
        set breed element1s
        set shape atom-shape
        set color random 139
        ;; to ensure that the colors are distinct, we only let
        ;; colors deviate from base color by plus or minus 3
        set color one-of base-colors - 3 + random 6
        set heading color
      ;; shift even columns down
      if pxcor mod 2 = 0  [ set ycor ycor - 0.5 ] 
  ; the two lines below are for NetLogo 3D. Uncomment them, if you are using NetLogo 3D.
  ; ask element1s [ set shape3d "sphere" ]
  ; ask element2s [ set shape3d "cube" ]
  ;; now set up the neighbors6 agentsets
  ask element1s [
    ;; define neighborhood of atoms
    ifelse pxcor mod 2 = 0
      [ set neighbors-6 element1s-on patches at-points [[0 1] [1 0] [1 -1] [0 -1] [-1 -1] [-1 0]] ]
      [ set neighbors-6 element1s-on patches at-points [[0 1] [1 1] [1  0] [0 -1] [-1  0] [-1 1]] ] 

;; makes initial box for image import

to makes-initial-box

;; makes initial box for random arrangement

to makes-initial-box-random

;; import image into turtles

to import-image
  let file user-file
  if file = false [ stop ]
  ;; imports image into patches
  import-pcolors file
  ;; converts the square grid to an hex grid
  ;; transfers the image to the turtles. Rounds the color values to be integers.
  ask turtles [
    set color round pcolor
    set heading color
  ;; erases the patches (sets their color back to black),
  ask patches [ set pcolor black ]

to define-neighboring-turtles
  ;; defines neighboring turtles. Some are "off" because atoms are in hexagons
  ask turtles [
    set neighboring-turtles (turtles at-points [
      [-1  1] [ 0  1] [1  1]
      [-1  0] [ 0  0] [1  0]
      [-1 -1] [ 0 -1] [1 -1]

to go  
  ;;initiates grain growth
  let total-atoms count turtles
  ;; stops when there is just one grain
  if average-grain-size >= total-atoms [ stop ]
  ;;limits grain growth to element1, element2 represent the stationary second-phase particles
  ask element1s [grain-growth]
;  ;; calculates grain variables at a given frequency to save CPU processing
;  ;; we + 1 to ticks to put it in sync with plots (that are updated in 'tick')
;  if remainder (ticks + 1) ticks-per-measurement = 0 [
;    count-grains-and-measure-grain-size
;  ]
  ;; advance Monte Carlo Steps (simulation time)
  ;; one Monte Carlo Step represents 'n' reorientation attemps,
  ;; where 'n' is the total number of atoms

to count-grains-and-measure-grain-size
  ;; we only do this for ticks > 0 since we can't take log of 0
  if ticks > 0 [
    set logtime log ticks 10
  if average-grain-size != 0 [
    set logaverage-grain-size (log (average-grain-size) 10)
  ;; we set the initial log time and grain size at 20 (we don't start
  ;; calculating grain size until then to give the system a bit of time to stabilize
  if ticks = 20 [
    set initial-logtime logtime
    set initial-loggrain-size logaverage-grain-size
  ;; only initiates grain size calculation after 20 ticks
  if ticks > 20 [
    ;; calculate the angular coefficient of the grain growth curve
    ;; since it is a log-log plot, it's the grain growth exponent
    set grain-growth-exponent (-1 * ((logaverage-grain-size - initial-loggrain-size) /
      (initial-logtime - logtime)))

to grain-count
  ;; count number of grains based on the number of linear intercepts
  let orientation-for-intercept-count 90 ;; direction of intercepts count
  let intercepts 0
  let total-atoms count turtles
  ;; asking only elements1 with xcor less than 24
  ;; those at 24 are on the 'edge of the world' which means
  ;; that they will never have neighbors to their right.
  ;; we therefore simply ignore them for this purpose.
  ask element1s with [ xcor < 24 ] [
    ;; checks if there is a turtle to the right for the intercept calculation
    let target-patch patch-at-heading-and-distance orientation-for-intercept-count 1
    ifelse target-patch != nobody and any? turtles-on target-patch [
      ;; If there is a turtle, checks if the heading is different.
      let right-neighbor one-of turtles-on target-patch
      if heading != [ heading ] of right-neighbor [
        ;; If heading is different, add 1 to 'intercepts'.
        set intercepts (intercepts + 1)
      ;; if there is no turtle, simply add 1 to 'intercepts'.
      ;; A turtle/nothing interface is considered as grain boundary.
      set intercepts (intercepts + 1)
  ;; we add one to intercepts so that zero intercepts = one grain, one intercept = 2 grains, etc.
  set average-grain-size total-atoms / (intercepts + 1)

;; Grain growth procedure - free energy minimization
;; if another random crystallographic heading minimizes energy, switches headings, otherwise keeps the same.

to grain-growth
  ;; if atom has no neighbors, it is surrounded by element2s, and will not change its orientation
  if not any? neighbors-6 [ stop ]
  ;; calculates the PRESENT free energy
  let present-heading (heading)
  let present-free-energy count neighbors-6 with [ heading != present-heading ]
  ;; chooses a random orientation
  let future-heading ([heading] of (one-of neighbors-6))
  ;; calculates the FUTURE free energy, with the random orientation just chosen
  let future-free-energy count neighbors-6 with [ heading != future-heading ]
  ;; compares PRESENT and FUTURE free-energies; the lower value "wins"
  ifelse future-free-energy <= present-free-energy
    [ set heading future-heading ]
    [ if (annealing-temperature > random-float 100) [ set heading (future-heading) ] ]
  ;; this last line simulates thermal agitation (adds more randomness to the simulation)
  ;;update the color of the atoms
  set color heading

;; drawing procedure

to turtle-draw
  if mouse-down? [    ;; reports true or false to indicate whether mouse button is down
    ask patch mouse-xcor mouse-ycor [
      ask element1s in-radius brush-size [
        set color read-from-string draw-color
        set heading color

;; in the drawing mode, erases the whole "canvas" with red

to erase-all
  ask element1s [
    set color red 
    set heading color

; Copyright 2005 Uri Wilensky.
; See Info tab for full copyright and license.

There are 15 versions of this model.

Uploaded by When Description Download
Uri Wilensky over 5 years ago Updated to NetLogo 5.0.4 Download this version
Uri Wilensky about 6 years ago Updated version tag Download this version
Uri Wilensky about 6 years ago Updated to version from NetLogo 5.0.3 distribution Download this version
Uri Wilensky almost 7 years ago Updated to NetLogo 5.0 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 8 years ago Model from NetLogo distribution Download this version
Uri Wilensky over 8 years ago Model from NetLogo distribution Download this version
Uri Wilensky over 8 years ago MaterialSim Grain Growth Download this version

Attached files

File Type Description Last updated
MaterialSim Grain Growth.png preview preview over 5 years ago, by Reuven M. Lerner Download
MaterialSim Grain Growth.png preview Preview for 'MaterialSim Grain Growth' over 5 years ago, by Uri Wilensky Download

This model does not have any ancestors.

This model does not have any descendants.