Material-modeling Support Download Files


This memo describes material-modeling support for PFC 7.0 as provided in the PFC 7.0 FISHTank (or fistPkg), and this memo corresponds with fistPkg7.3.

The following capabilities are provided by fistPkg7.3:

  • Material genesis of linear, contact-bonded, parallel-bonded,soft-bonded,flat-jointedand user-defined (3D hill)materialsinpolyaxial, cylindrical and sphericalphysicalvesselsor polyaxial periodic vessel.Material grains can beballs or clumps, and 3D flat-jointed materials of spherical, Voronoi or tetrahedral grains.Stress can be installed into the finalized periodicensemble(after bonding), and thenthis ensemble can be converted into a periodic brick whichis assembled into a larger geometric shape.Material tests are compression (confined, unconfined and uniaxial strain), diametral-compressionand direct-tension. Microstructural monitoring includes properties (such as grain-size distribution) with microstructural plotsetsandcrack monitoring for bonded materials.

Usage instructions are given in fistPkg-README.txt and summarized as:

  • Create a 2D or 3D material (using the appropriate MatGen project).
  • Perform compression, diametral-compression and direct-tension tests on the material (using the CompTest, DiamCompTest and TenTest projects).

Download Files

PFC 7.0

Material-Modeling Support Package, fistPkg7.3 (ZIP, 138 MB)

Material Modeling Support 7.3 (PDF, 16 MB)

Material Modeling Support 7.3, Materials 1 (PDF, 20 MB)

Material Modeling Support 7.3, Materials 2 (PDF, 6 MB)

Material Modeling Support 7.3, Materials 3 (PDF, 3 MB)

Material Modeling Support 7.3 Updated Webinar (PDF, 44 MB)

PFC 6.0

Material-Modeling Support Package, fistPkg6.6 (ZIP, 87 MB)

Material Modeling Support 6.6 (PDF, 16 MB)

Material Modeling Support 6.6, Materials 1 (PDF, 16 MB)

Material Modeling Support 6.6, Materials 2 (PDF, 6 MB)

Material Modeling Support 6.6, Materials 3 (PDF, 3 MB)

Material Modeling Support 6.6 Updated Webinar (PDF, 37 MB)

PFC 5.0

Material-Modeling Support Package, fistPkg26 (ZIP, 74 MB)

Material-Modeling Support Update Revisions

The first column of this table lists the fistPkg revision number; the second column lists the PFC release against which the fistPkg has been tested; and the third column describes the fistPkg revision. Note that each revision of the fistPkg is expected to operate with a PFC release that is current or newer than that listed. Since newer revisions of the fistPkg may use features available only in newer revisions of PFC, they may not be compatible with older revisions of PFC.

fistPkg ReleasePFC ReleaseDate / Description


  • Fix issue with {MatGen-Hill\\MatGen&Test-RUN.p3prj} that causes the material with suction not to converge to the desired initial 150 kPa confinement during the compression test. Fixed in PFC3D 7.00.159 {Fix Hill contact model bug - the moisture force was not properly included in the getForce and getMoment methods.}


  • Added contact-bonded material parameter cbm_shearsTensRatio.
  • Added parallel-bonded material parameter pbm_cohTenRatio.
  • Added soft-bonded material parameter sbm_cohTenRatio.
  • Added the ability to create 3D flat-jointed Voronoi- and tetrahedral-grain materials, perform material tests upon them and track
    cracks (see MatModelingSupport[fistPkg7.2]-ExampleMats2.pdf).
  • Added slide set describing flat-jointed material behavior (Documentation\FlatJointedMaterial_Behavior.pdf).
  • Added flat-jointed material parameters fjm_cohTenRatio, fjm_cohres and fjm_resmode. If fjm_cohTenRatio is on-zero, then cohesion at each contact is set equal to fjm_cohTenRatio times the current tensile strength. The other two parameters are flat-joint material properties that are new in PFC version 7.
  • Release of fistPkg for PFC 7.0. The package is ready for use.
  • fistPkg7.1 provides the same capabilities as fistPkg6.6.



  • Provide soft-bonded material and associated lab tests. The material codes specified by cm_matType have changed (see Table 1 in the material modeling support memo).
  • Modify crack tracking to display soft-bonded contacts that have broken (not those in softening state). Use the microstructural plot set {sbond interfaces} to display all grain-grain soft-bonded contacts as interfaces that can be turned on/off and colored by value of sb_state.
  • Modify TenTest to provide windows with (1) measurement-based axial stress versus boundary-based axial strain (pl-msa_bea), and (2) numbers of cracks versus boundary-based axial strain (pl-crk_bea). Make these windows be the default windows.



  • Complete user-defined material example. This example utilizes the hill contact model, which is an undocumented built-in contact model.
  • Provide function (mpDavg) to return average grain size. This runs significantly faster than calling mpComputeMicroStruc and then querying mp_Davg.


Bug Fixes.

  • Fix capability to carve cylindrical specimen out of a material block and perform compression tests upon it (see the header in sp.p3fis) --- the tests are only supported in 3D. The default behavior now uses a 12-sided cylinder, and ensures that the carved region is within that cylinder, yet still has a relatively large number of boundary grains that initially overlap the walls.


Bug Fixes and enhancements to crack-tracking package.

  • Fix crack-tracking package to work with PFC 6.00.8 by specifying an initial non-zero disk diameter for a new crack.
  • Modify crack filtering so that orphan cracks are excluded from the set of filtered cracks. Enhance crack filtering so that the filtering criterion can be greater than or less than a specified gap (controlled by ckFilterOpen).



  • Enhanced crack-tracking package so that ckForceUpdate runs fast by replacing fracture.prop items with fracture.extra items. When running lab tests with more than about 50000 cracks, the call to this function just before saving the state was taking upwards of 8 hours.
  • Enhanced mpMakeFromBrick (in ft.fis) to allow specification of specimen-center location.
  • Create capability to construct a specimen by assembling it from a periodic brick, and then perform tension and compression tests upon it (see the header in sp.p3fis) --- the tests are only supported in 3D.


Release of fistPkg for PFC 6.0. The package for PFC 5.0 uses the naming convention fistPkgM, where M is the package version number. The package for PFC 6.0 using the naming convention fistPkg6.N, where N is the package version number. The syntax of commands and FISH items has been modified to be compatible with PFC 6.0. The package is ready for use. The hill contact model, which is used by the user-defined material example, is not yet available. fistPkg6.1 provides the same capabilities as fistPkg26, and also provides the following enhancements.

  1. A slide set describing a suggested procedure for calibrating a flat-jointed material has been added to the Documentation directory.
  2. Support cm_matNameSAV such that if this name is not specified in mpParams, then it will default to 'PFCmat', and all second-level drivers (e.g., CompTest) will restore that name. Now all second-level drivers will begin with a generic restore with no need to change the restore string when running a particular model. The cm_matName is still provided, but it is used only when creating titles.
  3. Material can be created in a periodic space. Stress can be installed into the finalized periodic ensemble (after bonding), and then this ensemble can be converted into a periodic brick which is assembled into a larger geometric shape.


fistPkg26 is the fistPkg for PFC 5.0. No new features will be added to this package, only bug fixes will be made. All new features will be added to the fistPkg for PFC 6.0 (named fistPkg6.N, see above entry). Download fistPkg26 for PFC 5.0 HERE (*.zip, 73 MB).

Bug Fixes.

  1. Fixed bug in 3D faced-grain plot set, this now works!


  1. Added capability to create three types of microstructurally valid flat-jointed materials in both 2D and 3D (via fjm_rmulCode).
  2. Added capability to draw cracks with thickness proportional to gap in both 2D and 3D (via the crack plot set).
25 5.00.35


Consistency test against PFC 5.00.35 successful





  1. Support clumped grains to provide general grain shapes --- see the common material parameters cm_shape and cm_ctName. Examples of clumped-grain models for granular materials are given in the Linear and User-Defined Materials Examples in the fistPkg memo. An example of clumped-grain models for bonded materials is given in the Contact-Bonded Material Example.
  2. Modify crack-tracking logic: (a) to reduce slowdown caused by crack filtering, and (b) by setting default value of ckUpdateRate to be two million --- the cracks are updated (by a call to ckForceUpdate) at the end of each loading stage before creating the SAV file.
24 5.00.30


Consistency test against PFC 5.00.30 successful.

24 5.00.29


Consistency test against PFC 5.00.29 successful.

24 5.00.27



  1. Update PFC 5.0 from 5.00.24 to 5.00.27.
  2. Fix crack-tracking bug that caused the diameters of some flat-jointed cracks to be assigned to the wrong flat-jointed elements.
  3. Complete the flat-joint interfaces plot set to display the interface, coordinate systems and discretization.
  4. Add the faced grain plot set. Known bug: 3D faced grains are not being drawn correctly.
  5. New technical memo {Flat-Joint Contact Model [version 1]} in Documentation\FlatJointContactModel that provides a comprehensive and fully up to date description of the FJ formulation. There are some minor differences from the PFC 5 docSet. This memo also contains a two-grain test problem (in ExampleProjects\FlatJointContactModel\Test-TwoGrains) and exercises the faced-grain plot set.





  1. Enhance crack monitoring: (1) define the crack gap as the surface gap (associated with the contact model), instead of the gap between the two contacting balls; and (2) enhance crack filtering to display the gap-based filtering criterion in the plot caption.
  2. Rename master project directories to remove the "my" designator, for example:

myMatGen-X ==> MatGen-X, where
X = {Linear, ContactBonded, ParallelBonded, FlatJointed, Hill}
myCompTest ==> CompTest
myDiamCompTest ==> DiamCompTest
myTenTest ==> TenTest

22 5.00.24



  1. Replace use of term "deviatoric stress and strain" in Section 5.1 {Stress, Strain and Porosity in the Material} of the fistPkg memo with the term "deviator stress and strain." Modify all references to this term in the memo and in the project files, in particular, modify the title and y-axis label in all pl-wsd_wea views.\
  2. Clarify description of the Hertzian component of the hill contact model in Section 1.4 {Hill Material} of Potyondy (2016). Describe the grain-grain system as "two locally elastic spheres." Refer to the Hertzian component of the surface-interaction force model as Hertz-Mindlin springs [replaces use of Hertzian springs], with the Mindlin portion of the term denoting the tangential response. Provide a footnote summarizing the contact formulation of the Hertz-Mindlin springs, with associated references from which the general solution is obtained for sphere-sphere and sphere-plane contacts between two elastic bodies with different radii and elastic constants. Describe the Hertzian component of the surface-interaction force model as providing "...the nonlinear force-displacement response arising from mutual compression of two elastic bodies, which induces a local deformation of the bodies in the vicinity of the contact surface. The local deformation is determined by the shapes and elastic constants of the bodies in the vicinity of the contact surface." REFERENCE: Potyondy, D. (2016) "Hill Contact Model [version 4]," Itasca Consulting Group, Inc., Minneapolis, MN, Technical Memorandum ICG7795-L (May 13, 2016).
  3. Update PFC 5.0 from 5.00.23 to 5.00.24.
  4. Remove the MakeThenTest drivers for the myMatGen projects, and replace with following scheme. Provide run projects [MatGen&Test-RUN] for each material to create that material and perform appropriate laboratory tests upon it. Provide master run project [MatGen&Test_AllMats-RUN] to create and perform appropriate tests on all materials. Modify all projects to exit upon completion.
  5. Provide plot-generation data files for material genesis, and each laboratory test: X-MakePlots.{p2,p3}dat, where X = {MatGen, CompTest, DiamCompTest, TenTest}.
21 5.00.23



  1. Modify @mvListProps to list current and initial vessel dimensions. Fix the figures of the linear and hill example materials to show vessel dimensions at the end of material genesis, which are less than the initial vessel dimensions because the boundary-contraction packing procedure moves the vessel walls inward. The previous figures showed the initial vessel dimensions.
  2. Clarify specification of measurement regions within the material vessel--- see new material-vessel parameters mv_inset{D,L}Fac, and note the renaming of _mvMpFac{W,H} ==> mv_inset{D,L}Fac.
  3. Microstructural plotting is now off by default, it had been on by default. Microstructural plotting is turned on by @msOn. It can also be turned on at the end of material genesis by specifying [true] as the value of the new second parameter of mpMake in the material-genesis driver file. For large models, with more than 15000 grains, the microstructural plots require significant memory with a corresponding increase in save-file size. For large models, it is better to keep microstructural plotting off, and only activate it by calling @msOn when generating a microstructural plot.
  4. Reset grain displacements to zero after the seating phase of the tension and compression tests.
  5. Add MakeThenTest drivers to myMatGen projects.
20 5.00.23



  1. Enhance support for computation of grain size distribution via @gsdGetSizeOfPercentile(pct), which returns grain size corresponding to percentile {pct} for grain size distribution in GSD table created by @gsdMeasure.
  2. Improve microstructural monitoring (see Section 3.0 in fistPkg memo).
  3. Add description of resilent modulus computation as a means to quantify the deformability of a granular material (see Section 5.2 in fistPkg memo).
  4. Add the hill contact model to the fistPkg as a user-defined contact model. The hill contact model is described in Potyondy (2016a). The creation and triaxial testing of a hill material are described in Potyondy (2016b, User-Defined Material Example). A material-behavior study that compares the responses of the linear and hill materials for narrow and broad grain-size distributions is given in Section 2.3 of Potyondy (2016a). The following modifications were made to the user-defined material interface, and to the hill contact model:
    • Provide new file udm_hl.p3fis for udm redefinitions, and replace udm_setMatBehavior with hlm_setMatBehavior.
    • Rename hill model property suc_coef => suction.
    • Rename hill model parameters:
      • hlm_sucCoef => hlm_suction
      • hl_makeDry => hlm_makeDry
      • hl_makeWet(gm) => hlm_makeWet(psi, gm)

Potyondy, D. (2016a) "Hill Contact Model [version 4]," Itasca Consulting Group, Inc., Minneapolis, MN, Technical Memorandum ICG7795-L (February 26, 2016).
Potyondy, D. (2016b) "Material Modeling Support in PFC [fistPkg20]," Itasca Consulting Group, Inc., Minneapolis, MN, Technical Memorandum ICG7766-L (February 26, 2016).

19 5.00.22 01/12/16
Create microstructural plot sets --- see Section 3.2 {Microstructural Plots}. Hide many of the views, they are manipulated via the Documents button. Modify default values of _mvMpFacH and _mvMpFacW from 0.9 to 0.8; these values control the size of the measurement spheres used to measure stress and strain in the material.
18 5.00.22



  1. Modify compression test for bonded materials to provide two additional hidden views (pl-mer_wea, pl-mev_wea) to be used during UCS tests. The wall-based radial and volumetric strains are not measured during UCS tests, and thus, the corresponding measurement-based quantities must be used to plot radial and volumetric strain versus axial strain curves.
  2. Enhance microstructural monitoring to include: microstructural properties (overlap ratios [mp_ORs] and bond coordination number [mp_CNb]); crack filtering and gaps; and microstructural plots --- see Section 3.0 {MICROSTRUCTURAL MONITORING}.
17 5.00.21 09/22/15
  1. Enhance compression test to include uniaxial-strain test (by setting ct_testType = 2).
  2. Delete grains with centers lying outside of the material vessel at the end of step 2 of the packing phase.
  3. Compute grain size distribution (GSD) of synthetic material by calling sdMeasure(numBins) to create table GSD, which is displayed in view pl-GSD (see Section 2.9 {Microstructural Properties} of the material modeling support memo).
16 5.00.20

Minor enhancements.

  1. Force chains can now be displayed as either bi-colored to denote tension and compression or scale-colored to denote magnitude (see plot items: "Contact force chain" and "Contact force_mag"). This capability is described as follows. The macroscopically applied compressive load is carried by the granular material as force chains that propagate from one grain to the next across grain-grain contacts. The force-chain fabric is depicted as a network of cylinders, with a cylinder at each contact. Force magnitude corresponds with cylinder color and thickness, and force direction corresponds with cylinder orientation.
  2. Add {Section 5.4 Loading Rate} to memo {Material Modeling Support in PFC}.
  3. Improve setup phase of UCS test to move platens away from specimen at ten times the previous rate.
  4. Add geometry set "viewBox" to material-genesis to allow one to display a box of a specified size on each plot (via the Geometry plot item).
15 5.00.17 04/22/15
Add capability to create a user-defined material, with a user-defined material example that creates a 3D Hill material.
14 5.00.15 02/17/15
Add diametral-compression test for PFC2D, with usage example for the 2D parallel-bonded material.
13 5.00.15 02/05/15
Remove the packing parameters: pk_emod and pk_krat. These two properties are replaced by the properties of either the linear material group (lnm_emod and lnm_krat) or the user-defined contact model (as specified in the udm_setMatBehavior FISH function).
12 5.00.15 02/02/15
Two enhancements: (1) Add a spherical material vessel. (2) Add diametral-compression test for PFC3D, with usage example for the parallel-bonded material. Break the material-modeling support memo into three related memos named "Material-Modeling Support in PFC," and "Material-Modeling Support in PFC (Example Materials {1,2}."
11 5.00.15 01/27/15
Two modifications: (1) Fix bug in computation of servomechanism gain in axial direction for 3D cylindrical vessel, and improve computation of wall-based stresses (now controlled by mv_wAreaMode). (2) Add Potyondy (2014) to documentation directory (see reference in entry for fistPkg 10).
10 5.00.15 01/20/15
Modify "Material-Modeling Support in PFC" memo to correspond with updated PFC 5.00.15 documentation set, and to refer to Potyondy (2014). Enhance compression test to support fully unconfined tests. [REFERENCE: Potyondy, D.O. (2014) "The Bonded-Particle Model as a Tool for Rock Mechanics Research and Application: Current Trends and Future Directions," Geosystem Engineering, 17(6), 342-369.]
09 5.00.14 11/17/14
PFC 5.0 FISHTank released to users as fistPkg09.
08 5.00.14 10/20/14
Update the PowerPoint slide set that summarizes Potyondy (2014a). REFERENCE: {Potyondy, D. (2014a) "Material-Modeling Support in PFC," Itasca Consulting Group, Inc., Minneapolis, MN, Technical
Memorandum ICG7766-L, October 20, 2014.}
07 5.00.9 10/10/14
Initial release of the PFC 5.0 FISHTank, which provides the following capabilities (for both PFC2D and PFC3D): material genesis of linear, contact-bonded, parallel-bonded and flat-jointed materials (all grains are balls) in physical material vessels (cylindrical and polyaxial) with compression and direct-tension testing.
06 5.00.9 09/19/14
Minor enhancements since fistPkg05. fistPkg06 has been released for selective internal Itasca review.
05 5.00.9 09/04/14
Material genesis of linear, contact-bonded, parallel-bonded and flat-jointed materials in physical material vessel with compression and direct-tension testing (PFC3D only, all grains are balls). Not yet available: (1) extend to support PFC2D, (2) allow grains to be clumps, (3) provide Brazilian-tension and fracture-toughness tests, (4) provide smooth-jointed interface and (5) provide stress-installation procedure.
04a 5.00.9 07/25/14
THIS IS A PRIVATE VERSION of ongoing developments, created for use of Derrick Blanksma. It supports creation of a linear material, and compression testing of that material. Note that it has been tested with PFC 5.00.9, it should probably work with more recent versions of PFC as well.
03 5.00.9 06/25/14
Modified interface to compression-test procedure to make it correspond with description in the memo: "Material-Modeling Support in PFC."
02 5.00.9 06/22/14
Material genesis and compression testing can be performed on the linear material for which all grains are balls.
01 5.00.7 06/10/14

Establish initial tank to support creation of linear material and compression testing (PFC3D only).

Latest News
  • Itasca has announced the release of FLAC2D v9 Itasca has announced the release of FLAC2D v9, revolutionizing the way we analyze and predict...
    Read More
  • 6th Itasca Symposium on Applied Numerical Modeling The next Itasca Symposium will take place June 3 - 6, 2024, in Toronto, Canada....
    Read More
  • Itasca International Inc. announces the Selection of its New CEO Itasca International Inc. announces the Selection of its New CEO ...
    Read More

Upcoming Events
26 Aug
FLAC3D V9.1 and Griddle V2.0 2024
... Read More