Users guide to DISC: Stress-based DiscreteElement Method software

Anders Damsgaard Christensenanders.damsgaard@geo.au.dk

http://cs.au.dk/~adc/

Last revision: October 19, 2010Version 0.3

AbstractThis document is based on notes and personal experiences using the

DISC discrete element modelling software and Matlab configuration meth-ods, developed by David Lundbek Egholm, Department of Geology, Uni-versity of Århus. This document is a work in progress, and is still in anearly, unfinished state. This document is typeset with LATEX. The marginis wide (LATEX standard) to make space for handwritten notes.

1

SDEM - DISC CONTENTS

Contents1 Theory 3

1.1 The DISC algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 31.1.1 Movement of the walls . . . . . . . . . . . . . . . . . . . . 61.1.2 The predictor . . . . . . . . . . . . . . . . . . . . . . . . . 61.1.3 Updating neighbor lists . . . . . . . . . . . . . . . . . . . 71.1.4 Contact searching . . . . . . . . . . . . . . . . . . . . . . 71.1.5 Strain rates and stress tensors . . . . . . . . . . . . . . . . 71.1.6 Forces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.1.7 Corrector . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.1.8 Movement of ’free’ walls . . . . . . . . . . . . . . . . . . . 101.1.9 File output . . . . . . . . . . . . . . . . . . . . . . . . . . 101.1.10 End of simulation . . . . . . . . . . . . . . . . . . . . . . 10

1.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.2.1 Particles and computational time . . . . . . . . . . . . . . 101.2.2 Parallel computing . . . . . . . . . . . . . . . . . . . . . . 11

1.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2 Compiling 11

3 Model setup 123.1 Creating the particles . . . . . . . . . . . . . . . . . . . . . . . . 123.2 Setting experiment parameters . . . . . . . . . . . . . . . . . . . 123.3 Coloring particles . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.4 Introducing heterogenieties . . . . . . . . . . . . . . . . . . . . . 143.5 Cyclic border-conditions . . . . . . . . . . . . . . . . . . . . . . . 14

4 SDEM simulation using DISC 15

5 Data analysis in Matlab 155.1 Exporting plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.2 Importing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Saving simulation results 186.1 Copying particle assemblages . . . . . . . . . . . . . . . . . . . . 18

A Folder structure 20

B DEM parameter structure in MATLAB 26

C Sample: template.m for shear-test 27

References 28

2

SDEM - DISC

1 TheoryThe DISC-software is used for (S)DEM simulations, and the methods and resultswere presented in two consecutive scientific articles1. Consult these for a fulltheoretical background:

1. Egholm, D. L. (2007), A new strategy for discrete element numerical mod-els: 1. Theory, J. Geophys. Res., 112. Cited as Egholm (2007)

2. Egholm, D. L., Sandiford, M., Clausen, O. R., Nielsen, S. B. (2007), A newstrategy for discrete element numerical models: 2. Sandbox applications,J. Geophys. Res., 112. Cited as Egholm et al. (2007)

The calculations are done by the DISC-software, written in C and compiled bythe user, and all model setup and configuration is done in Matlab, using the.m-functions included. I have since added some additional Matlab functions2,which are useful for exporting graphics and when working with models thatshear particle assemblages horizontally.

Although three-dimensional simulation support is partly implemented in theDISC source code, the present state limits usage to two-dimensional simulations,where the particles can be seen as flat discs or cylinders with infinite depth,with three degrees of freedom: Two translational (spatial) and one rotational(Egholm, 2007). Each particle has a friction angle (φ) and an angle of rollingresistivity (ψ), which represents the slope where a particle under the influenceof gravity would begin to respectively slide or roll. If φ > ψ, the general modeof particle contact motion is sliding/shearing, and particle rolling if φ < ψ.The particles are represented by perfectly round circles, so to obtain the mostrealistic results similar to real geological materials, rotational movement due tointer-particle collision and movement is greatly restricted in the code. The angleof rolling resistivity (ψ) in real materials is a function of both particle surfacemorphology, roundedness and elongation.

In the following examples, commands starting with the symbol ’$’ are ex-ecuted in the terminal of the operational system, and ’>>’ means executionin Matlab. After compiling the DISC binary, the procedure of a creating andhandling a simulation is typically arranged in the following order:

1. Setup of particle assemblage, physical properties and conditions in Matlab,described in section 3, page 12.

2. Execution of DISC software, which simulates the particle behavior as afunction of time, as a result of the conditions initially specified in Matlab.Described in section 4, page 15.

3. Inspection, analysis, interpretation and visualization of DISC output inMatlab. Described in section 5, page 15.

1.1 The DISC algorithmThe DISC software calculates particle movement and rotation based on the forcesapplied to it, by application of Newton’s law of motion (Newton’s second law

1Full reference list can be found in the appendix, page 282Available from http://cs.au.dk/~adc/files/disc-mfiles-adc.zip. Put these into the

mfiles-folder of the DISC software.

3

SDEM - DISC 1 THEORY

with constant particle mass: Fnet = m · acm). This is done in a series ofalgorithmic steps, see figure 1. The steps are explained in the following sectionswith reference to the DISC-source file; disc.c. The intent with this documentis not to give a full theoretical background of the methods, but rather how thesoftware performs the calculations.

[18] Perhaps for the above mentioned reasons, most DEMstudies published in the field of structural geology focus onthe dynamics of predefined shear zones only [Morgan andBoettcher, 1999; Morgan, 1999; Strayer and Suppe, 2002;Imber et al., 2004] and do not attempt to simulate theirentire growth history. Some [Finch et al., 2003, 2004]choose to ignore the frictional strength of the materialmodeled, using a purely cohesive model with viscousdamping resulting in shear zone orientations of !45!.Others [Donze et al., 1994], use a particular triangularlattice geometry for imposing unphysical constrains on theparticle flow directions, forcing shear bands to form atangles of 60!.

3. Stress-Based Discrete Element Method

[19] In this section the mathematical details of SDEM arepresented. First, kinematic aspects including the strain ratemeasure, are described, and later, the dynamical relationsare explained. The algorithmic steps of SDEM are sche-matically presented in Figure 1.

3.1. Kinematics

[20] In the following, the formulation is limited to spher-ical or disc shaped (infinite cylinders) particles with threedegrees of freedom; two translational and one rotational asin a two dimensional setup, albeit all relations are easilygeneralized to three dimensions. Each particle in the dis-crete system obeys the following conservation laws oftranslational and rotational momentum:

m!x " F and I _w " t #2$

m is the particle mass, x the particle position vector, and Fthe total force vector. t is the total moment, w the angularvelocity, and I is the moment of inertia. A dot indicates timedifferentiation. Equation (2) is integrated using a predictor-corrector leapfrog time stepping scheme (see Figure 1). Twoparticles of radii Ra and Rb, positioned at xa and xb andwhere xab % xb & xa, are said to be in contact if their virtualoverlap xab % Ra + Rb &jxabj is positive. At the contact, unitvectors nab % xab/jxabj and sab % [n2ab, & n1ab] are used forsplitting contact forces and velocities in normal and shearcomponents. In particular, the normal, vn, and shear, vs,relative velocities are

vn " v iabniab and vs " v iabs

iab ' waRa ' wbRb #3$

where vab % vb & va. In equation (3) and in the following,Einstein’s summation convention of repeated indices isadopted for the superscripts. As illustrated by Figure 2, thecontact point is located at ~xab and its relative velocity is~vab = 1

2(vnnab + vssab).[21] For each particle a strain rate tensor is defined

_e ija " 1

2rv ija 'rv ji

a

! "

#4$

Here, rvij is the velocity gradient measured at the particlecenter. In calculating this, use is made of kernel-basedinterpolation (see Appendix A). Then

rv ija "X

b

rwib xa# $~v j

ab #5$

Figure 1. Outline of the SDEM algorithmic steps. The steps are performed in every small time step oflength Dt and are necessary for accomplishing the predictor-corrector leapfrog time integration.Computationally, the costs of SDEM and most DEM formulations are comparable.

B05203 EGHOLM: A NEW STRATEGY FOR DISCRETE ELEMENTS, 1

4 of 16

B05203

Figure 1: Outline of the SDEM algorithmic steps. From Egholm (2007).

The structure of disc.c is the following: The file begins with inclusion ofC library files, and some additional custom files (line 1–8). After this part, allfunctions are declared. When the DISC binary is executed, the calculations aredone from the main(...) (l.1915) function. The sequence of events is thefollowing:

1. Declaration of all variables, some of which are pointers (Vectors: markedby *) or double pointers (Matrices: marked by **).

2. Specification of the number of dimensions (nd = 2) and the particle sort-ing hierarchy (see more in section 1.1.3).

3. Reading of input-files fromMatlab (rmode.dat, particles.dat, partch.dat,grid.dat, walls.dat)

4. On the base of these data; initiating particles, the grid, the walls, thelength of the simulation and the time interval between output files.

5. Writing output0.dat

6. Calculation of the length computational time steps (dt) via equation 1,where length of the time intervals is defined by:

∆t < min(√

ρR2

K

)(1)

4

SDEM - DISC 1.1 The DISC algorithm

Name Type Descriptionx[i][d] double Particle coordinates. Returns the coordinate of par-

ticle i in dimension d. E.g. x[124][1] returns x-axisplacement of particle 124.

velo[i][d] double Particle velocity. Returns the velocity of particle iin dimension d.

acc[i][d] double Particle acceleration. Returns the acceleration ofparticle i in dimension d.

angvelo[i] double Angular velocity of particle i. Note: This degreeof freedom is only implemented for 2D simulationssince the orientation of the axis of spin is not definedanywhere.

angacc[i] double Angular acceleration of particle i.radius[i] double Radius of particle i.pressure[i] double Pressure exerted onto particle i.eplast[i] double Accumulated plastic deformation of particle i.np long Number of particles (read from line 1 in

/input/particles.dat)Np long Number of initial particles (read from

/input/rmode.dat)nd int Number of dimensionstime double Current time in the simulation.totaltime double Total time of the simulationtotal_time double Total time, read from /input/rmode.dat.filetime double Timespan between file output.dt double Length of calculation interval.periflag int Periodic/cyclic boundaries (0 or 1)

Table 1: Some important variables in disc.c. The integer i refers to the particlenumber.

5

SDEM - DISC 1 THEORY

where ρ is the particle material density, R is particle radius, and K isbulk modulus. This implies, that if all particles have the same bulk mod-ulus and material density, the radius of the smallest particle decides thetimestep length.

After these initial steps, DISC enters the main time-loop, where it does its cal-culations until the simulation time reaches the specified length of the simulation(in seconds; time < total_time). The algorithm steps (as shown in figure 1)are described in the following subsections:

1.1.1 Movement of the walls

The walls are moved according to the corresponding values in the variablewallspeed[i][d], where i is the number of the wall, and d is one of the dimen-sions. The walls can also be moved according to pressure, with wallpress[i][d].

1.1.2 The predictor

The predictor-function predicts the kinematics of the particles (from their valuesat the end of the last timestep) by allocating the positions, velocities, acceler-ation, etc. of all particles, and moves them according to these values. This isdone by the following Newtonian derived equations for particle i (modified fromEgholm (2007)). Bear in mind that a = F

m . Subsript p denotes predicted values:

vip = vi

0 + ∆t Fi0

mi(2)

ωip = ωi

0 + ∆tIτ0 (3)

xi = xi0 + ∆tvi

0 + ∆t2t

F i0

mi(4)

In disc.c, these calculations for each particle correspond to:885 /∗ loop dimensions ∗/886 f o r (j=1;j<=nd ; j++) {887888 /∗ po s i t i o n s ∗/889 x [ i ] [ j ] += dt∗velo [ i ] [ j ] + 0 .5∗ dt∗dt∗acc [ i ] [ j ] ;890891 /∗ v e l o c i t i e s ∗/892 velo [ i ] [ j ] += acc [ i ] [ j ]∗ dt ;893894 }/∗ j ∗/895896 /∗Accumulated disp lacement along the x−ax i s ∗/897 xdisp [ i ] += dt∗velo [ i ] [ 1 ] + 0 .5∗ dt∗dt∗acc [ i ] [ 1 ] ;898899 /∗Angular v e l o c i t y ∗/900 angvelo [ i ] += angacc [ i ]∗ dt ;901902 /∗Rotation ∗/903 rotation [ i ] += dt∗angvelo [ i ] + 0 .5∗ dt∗dt∗angacc [ i ] ;

6

SDEM - DISC 1.1 The DISC algorithm

If the setup includes periodic/cyclic boundaries (periflag = 1), and a particlemoves out of one side, coordinates are corrected so the new position is at theopposite side of the assemblage (see more in section 3.5).

1.1.3 Updating neighbor lists

For minimizing of the computational requirements when searching for contacts(see next section), the contacts are identified using a box sorting algorithm andneighbor lists (Smith et al., 1997).

In short, the particle assemblage is divided in different levels. The mostcoarse (largest with regard to particle numbers) division is done into lists calledcities, where each consists of up to 100 particles (ncn). A finer grid is made outof blocks, which contain up to 20 particles (nbn). The finest division is madeinto cells, which each can contain up to 10 particles (nno). In addition, it isdefined that each particle can have no more than 10 neighbors at a time (nt).

The neighbor lists are disturbed by spatial movement and diffusion of theparticles, which is why they need to be rewritten from new data after a cer-tain timespan. The larger the division, the longer the timespan. For each 100timesteps, the cities are calculated from scratch, while the block-lists are up-dated after 10 timesteps. The cells are updated in each timestep.

1.1.4 Contact searching

The function topology(...) (l.420) contains a loop that runs once per par-ticle in the assemblage. For each particle, it is examined what the distanceand direction (inter-particle vector) between the particle itself center and all ofthe other particles’ centers in the block neighbor list are. Afterwards delta iscalculated:

δab = dab −Ra −Rb (5)

where dab is the distance between the centers of the particles a and b, and Ra

and Rb being radii. If there is physical overlap between the particles (δab < 0),the particles are added to the ntopo list.

A similar method is used for simulating the physical repulsion of the walls,in the function wall_topology(...) (l.1353).

1.1.5 Strain rates and stress tensorsStrain, ε (def): Themagnitude of deforma-tion; equal to the changein the dimensions of a de-formed object divided byits original dimensions.Hooke’s law:

E ≡ StressStrain = σ

ε

where E is Young’s mod-ulus.

The function update(...) (l.1019) updates the velocity and density gradients,after the effect of the walls has been calculated in wall_topology(...), and theinter-particle contacts have been mapped in topology(...). For each particleit calculates the strain rates, the stress tensors, the friction, sliding and rollingon particle contact interfaces, the pressure exerted onto it, and the accumulatedplastic deformation (eplast[i]). The general form of the strain rate rate tensorfor each particle is:

εija = 1

2(∇vija +∇vji

a ) (6)

where ∇vija is the velocity gradient measured at the particle center. Using

kernel-based interpolation, the strain rate for each particle is calculated with

7

SDEM - DISC 1 THEORY

the following equation, which is essentially a sum of contact strain rate contri-butions:

εija = 1

2Ra

∑b

dw(qab)(viabn

jab + vj

abniab) (7)

where qab is the normalized distance between the particle center (xa) and thecontact point (xab), dw(qab) is the kernel function gradient (for two-dimensionaldiscs dw(qab) = −1), vi

ab is the relative contact point velocity.Young’s modulus (E, young) is set in set in template.m in Matlab, and is a

measure of the stiffness of an isotropic elastic material3. Young’s material is aconstant value in DISC, which means that the material is linear and isotropic,and obeys Hooke’s law (see margin note). Poisson’s ratio (ν) is the ratio, when asample object is stretched, of the contraction or transverse strain (perpendicularto the applied load), to the extension or axial strain (in the direction of theapplied load) 4. The value of Poisson’s ratio is set in the Matlab file setup.m.

The bulk- and shear moduli are calculated from Young’s modulus and Pois-son’s ratio, and are constant for all particles:

1137 /∗moduli ∗/1138 bulkmod = young /(3 .0∗ (1 .0 −2 .0∗ poisson ) ) ;1139 shearmod = young /(2 .0∗ (1 .0+ poisson ) ) ;

The bulk modulus (K) is a measure of the substance’s resistance to uniformcompression. It is defined as the pressure increase needed to cause a givenrelative decrease in volume. The shear modulus (or modulus of rigidity) (G) isdefined as the ratio of shear stress to the shear strain.

The stress tensor consists of a spherical and a deviatoric part (stressdev[i][j],where j = 1, 2, 3):

σij = −Pδij + sij (8)

where P is pressure and sij is the deviatoric part. The pressure is calculatedfrom the particle dilation (εii) and the bulk modulus (K).

The stress tensor is returned as a vector stress[i][j], where j = 1, 2, 3).

1.1.6 Forces

In the function get_force(...) (l.509) all forces (contact and gravitational)and the resulting direction of acceleration are calculated. The total force act-ing on a particle is found by summing contributions from gravity and particlecontacts:

F ia = mag

i +∑

b

f iab (9)

where ma is the mass of the particle and gi being the gravitational acceleration.The force-variable is represented by component values in the cartesian coordi-nate system. Initially, the gravitational force is calculated for each particle, andthe variable values for horizontal force, rotational moment and couple (rotationwithout acceleration of the centre of mass):

3http://en.wikipedia.org/wiki/Young’s_modulus4http://en.wikipedia.org/wiki/Poisson’s_ratio

8

SDEM - DISC 1.1 The DISC algorithm

610 f o r (i=1;i<=np ; i++) {611 force [ i ] [ 1 ] = 0 . 0 ;612 force [ i ] [ 2 ] = −gravity∗mass [ i ] ;613 moment [ i ] = 0 . 0 ;614 couple [ i ] = 0 . 0 ;615 }

The contact force between particles a and b (f iab) is calculated the following

way:f i

ab = −12

(A(Ra)σij

a +A(Rb)σijb

)nj

ab (10)

where A is the surface area of the particle contact interface (width in the caseof particles represented by 2D discs, σij is the stress tensor and nj

ab is thenormal vector to the contact surface (rpp[d]). The moment (the rotationalforce, moment[i] is calculated, and exerted to both parts involved in the inter-particle interaction.

The force is divided into a normal- (fn) and shear-component (fs) with re-spect to the orientation of the contact plane. The resulting force for particle a(F i

a) is a two-dimensional vector (force[i][d], i: particle number, d dimen-sion). The repulsive force exerted onto particle a from e.g. particle b is alsoapplied to particle b, however with opposite direction.

The last function called in this step is named add_bpress(...) (l.1722),which adds any boundary pressures, e.g. by a wall.

1.1.7 Corrector

The corrector(...) (l.928) uses the updated contact forces and momentsto update particle accelerations and velocities to more appropriate values thataccount for the forces exerted to the particle during the timestep:

vi = vip + ∆t

2F i − F i

0m

(11)

ω = ωp + ∆t2

τ − τ0

I(12)

In the DISC code, this is done using the following syntax:955 /∗ save o ld a c c e l e r a t i o n s ∗/956 old_acc [ j ] = acc [ i ] [ j ] ;

964 acc [ i ] [ j ] = force [ i ] [ j ] / mass [ i ] + cforce [ i ] [ j ] / mass [ i ] ; ←↩/∗new a c c e l e r a t i o n s ∗/

965 velo [ i ] [ j ] += 0.5∗ dt ∗( acc [ i ] [ j ] − old_acc [ j ] ) ; /∗new ←↩v e l o c i t y ∗/

and for the angular velocity:986 /∗ save o ld angular a c c e l e r a t i o n ∗/987 old_angacc = angacc [ i ] ;

9

SDEM - DISC 1 THEORY

1008 angvelo [ i ] += 0.5∗ dt ∗( angacc [ i ] − old_angacc ) ;

1.1.8 Movement of ’free’ walls

The last function to be called in each timestep is move_walls(...) (l.1620),which moves the ’free’ walls according to the contact pressure that is exerted tothem from the particles:

1626 /∗ loop wa l l s ∗/1627 f o r (i=1;i<=nw ; i++) {16281629 i f ( wfree [ i ] > 0) {16301631 /∗wal l normal∗/1632 normal [ 1 ] = ( walls [ i ] [ 4 ] − walls [ i ] [ 2 ] ) /dw [ i ] ;1633 normal [ 2 ] = ( walls [ i ] [ 1 ] − walls [ i ] [ 3 ] ) /dw [ i ] ;16341635 /∗normal f o r c e ∗/1636 fn = wforce [ i ] [ 1 ] ∗ normal [ 1 ] + wforce [ i ] [ 2 ] ∗←↩

normal [ 2 ] ;16371638 /∗ a c c e l e r a t e wa l l − mass assumed 10∗/1639 wallspeed [ i ] [ 1 ] += dt∗fn∗normal [ 1 ] / 1 . 0 e1 ;1640 wallspeed [ i ] [ 2 ] += dt∗fn∗normal [ 2 ] / 1 . 0 e1 ;16411642 }/∗ f i ∗/16431644 }/∗ i ∗/

A wall is made ’free’ by setting the variable DEM.walls.free in template.min Matlab. As an example, the line "DEM.walls.free = [0,1];" makes thesecond wall free to move due to pressure.

1.1.9 File output

Each time the simulation time has run for the timespan specified in the variablefiletime (or in Matlab: DEM.rm.filetime), a new output file is created,

1.1.10 End of simulation

When the time in the simulation is not anymore smaller than the total time,the simulation ends, and all variables are freed from the computers memory.Afterwards, the disc binary exits.

1.2 Performance1.2.1 Particles and computational time

With an increasing amount of particles, obviously more calculations have to beperformed each time step, which directly translates to an increasing computa-tional time.

10

SDEM - DISC 1.3 Errors

The size of the computational timestep length is fixed at a sufficiently lowvalue, so that the particle response is calculated several times while the speed ofsound (the strain signal) travels through even the smallest particle, see equation1. If there is a large variety of particle sizes, the particle with the smallest radiusdetermines dt for all calculations.

1.2.2 Parallel computing

The DISC code is not parallized, i.e. it does not carry out multiple calcula-tions simultaneously. Many modern workstations, servers—even laptops—havemultiple CPU cores, so a single execution of the DISC binary will only occupyone of these cores, in which the usage will be close to 100%. If it is desiredto carry out multiple experiments as fast as possible, a solution is to copy thecode into several folders, setup different experiments, rename the binaries foridentification in process charts, and run them simultaneously. It is crucial tocopy the root folder, because the DISC binaries otherwise overwrite each othersdata output. On UNIX systems, the active processes can be monitored withthe command ’top’.

1.3 ErrorsInside disc.c, many conditions are continuously checked, and if they are notmet, an error message is written to logfile.txt, which can be found inside theoutput/ folder. The program usually crashes afterwards, and gives a systemerror message to the screen.

Most often, crashes are caused by erroneous setup of the simulation in Mat-lab. As an example, if a particle move outside the initial grid, the programcrashes. It is therefore important to make sure that the grid is at least solarge that it at all times contains all particles, regardless of deformation andmovement, especially when using ’free’ walls (see section 1.1.8).

If other errors are encountered, it is useful to investigate the problem withe.g. GDB; the standard GNU Debugger. This way, the program is frozen ifan error encounters, and all particle values can be printed. Below is an usageexample of GDB with a crashing DISC experiment:

$ gdb . / source/disc( gdb ) run $PWD

−−− DISC crash and GDB output −−−( gdb ) backtrace f u l l( gdb ) p x [ 1 2 4 ] [ 1 ]

where the last line prints the x-axis coordinate of particle 124 (see table 1).

2 CompilingThe software consists of several files and sub-directories, see appendix A. Theprerequisite for compiling the software is a C compiler, such as GCC. A customcompiling script is included. Run the following command in the software rootfolder in the terminal:

11

SDEM - DISC 3 MODEL SETUP

$ cd source$ . / make

The compilation output will contain some warnings about unused variables, butthese can be discarded.

3 Model setupIn Matlab, enter the software’s mfiles/-directory as the current folder (exam-ple: » cd /code/shear/mfiles/). For each new experiment setup, it mightbe a good approach to copy the software root-folder, thus saving configurationsand data.

3.1 Creating the particlesTo begin with, the model surroundings and the particles (which are gauss-distributed around a mean particle size) are created. These particles are situatedin a fixed grid-like setup, between the particle centers.

Using the Matlab Editor or another editor, open the file mfiles/basicsetup.m.Here you set:

• Length and height of the model

• The number of particles

• The filename of the output file, and the included parameters.

Here, the grid size determines the particle sizes. After the file is saved, create thespecified model setup using the following command in Matlab. The parameter1 enables graphical output:

>> basicsetup (1 )

Hint: consolidate.m iscreated solely for consol-idation purposes. Thisleaves template.m intactfor shearing, etc.

Usually, the next step is to consolidate the particles under the influence ofgravity and/or moving walls. Before the simulation (see section 4), physicaloptions are set in template.m.

3.2 Setting experiment parametersThe physical parameters are set in another file. When setting various parametersin the files, the units are of SI standard. Using your favorite editor, open thefile mfiles/template.m. Edit the following parameters to desired values:

• The filename of the input file (e.g. ’myconfig’)

• The number of walls, their velocities and friction.

• The angle of internal friction and cohesion.When consolidating aparticle assemblage, it isa good idea to use φ = 5◦

and C = 0 Pa• Young’s modulus.

• The gravitational acceleration

12

SDEM - DISC 3.3 Coloring particles

• Length of time for the simulation

• Time interval for outputting data for visualization.

After saving the changes, run the script in Matlab:>> template (1 )

3.3 Coloring particlesMatlab can automatically color particles in different shades by assigning dif-ferent matflag(I) values to the particles contained in quantity I. In the filetemplate.m, in section %Layers, the zoning can be set on base of any param-eter. Often it is helpful to use different coloring on the basis of the initialcoordinates of the particles, thus being able to create visual layering for use ascompletely passive strain markers. In this example, a new color is given to theparticles in a 0.1 m interval on the y-axis:

%Hor i zonta l l a y e r i n gDEM = layer ( DEM , 0 . 1 ) ;

Equally, a vertical layering may be created by the column(...)-command:%Ver t i c a l l a y e r i n gDEM = column ( DEM , 0 . 1 ) ;

The above statements assigns two different matflag-values to the particles, withlayer thickness as the second parameter. The grains can also be given a rangeof matflag-values, as a function of initial y-position:

%Hor i zonta l l a y e r i n gy = DEM . particles . position ( : , 2 ) ;I = y > 0 ;DEM . particles . matflag (I ) = 0 ;I = y > 0 . 1 ;DEM . particles . matflag (I ) = 0 . 1 ;I = y > 0 . 2 ;DEM . particles . matflag (I ) = 0 . 2 ;

A vertical band can be created from the initial x-positions:%Ver t i c a l c o l o r l a y e rx = DEM . particles . position ( : , 1 ) ;I = x > 0 ;DEM . particles . matflag (I ) = 0 ;I = x > 0 . 0 5 5 ;DEM . particles . matflag (I ) = 1 ;I = x > 0 . 0 6 5 ;DEM . particles . matflag (I ) = 0 ;

By enabling the colorbar, the scale reflects the values set as DEM.particles.matflag(I)above. The process can also be automated, which is useful if a regular horizontal

13

SDEM - DISC 3 MODEL SETUP

coloring is wanted:%Hor i zonta l l a y e r i n gy = DEM . particles . position ( : , 2 ) ;ymax = max( DEM . particles . position ( : , 2 ) ) ;i = min( DEM . particles . position ( : , 2 ) ) ;interval = 0 . 0 1 ; %Color−l a y e r th i c kne s s

whi l e (i < ymax )I = y >= i ;DEM . particles . matflag (I ) = i ;i = i + interval ;

end

3.4 Introducing heterogenietiesUntil now, all grains in the model have the same physical properties. Het-erogenieties can be introduced in the same way as the coloring above. Thefind()-function in Matlab can be used to set different properties on particles,that fulfill a specific requirement, e.g. are contained between geometric border-values in the coordinate system in the initial setup.

Please note, that these deviant values need to be set after the general physi-cal values in template.m. The following is an example, that assigns new valuesfor cohesion (C) and angle of internal friction (φ) for the bottom 0.02 m parti-cles:

%%Het e r o g en i e t i e s%Weak bottom lay e ry = DEM . particles . position ( : , 2 ) ;I = f ind (y < 0 .02 ) ; %Pa r t i c l e s de f i ned as quant i ty Iphi = 1 ; %Angle o f i n t e r n a l f r i c t i o nDEM . particles . friction (I ) = tan ( phi∗ pi /180) ∗ones ( l ength (←↩

I ) , 1 ) ;C = 10 ; %CohesionDEM . particles . cohesion (I ) = C∗ones ( l ength (I ) , 1 ) ;DEM . particles . matflag (I ) = 2 ;

Here, the affected particles are given a different matflag-value, for visual iden-tification of the particles with different properties.

3.5 Cyclic border-conditionsFor simulating mechanisms that involve large horizontal strains, as in a ring-shear apparatus, it is a good approach to make the left and right borders cyclic.That means that a particle disappearing out of the right side will reappear inthe same vertical position in the left side. Particles can affect each other withcontact forces in the same way. This has the advantage that the total numberof particles can be kept low in relation to a very wide model setup.

The cyclic borders are in Matlab enabled by the command DEM.rm.periflag= 1. In this configuration, only the top and bottom walls are needed. A specificnormal-pressure is applied in pascal (Pa−1 = N

m ) (denote the value with a

14

SDEM - DISC

negative sign for downward oriented pressure). The shearing motion is appliedby fixing the bottom particles to a horizontal velocity of zero (0), and movingthe uppermost particles at a constant horizontal velocity (e.g. 0.1 m

s ). Theparticles are not fixed in the vertical directions, since particles still need to beable to pass each other by volumetric expansion.

See appendix C for an example on how to set up a model with conditionssimilar to a ring-shear apparatus. Please note, that the shearing velocities aremuch higher than found in both ring-shear devices and glaciers. The realistic,slow speeds produce deformation too slowly to finish the calculations over areasonable timespan, since the size of the timesteps are independent of theshearing velocity.

4 SDEM simulation using DISC

After the initial model preferences have been set up (in template.m), the SDEM-calculations by the DISC binary are initiated by the script:

$ . / start

This script flushes old output data and image files, and executes the disc binaryfrom the source/-folder. The binary will run in the background, so the shellwindow can be closed without halting the execution. In Matlab, the state ofthe calculations can be checked with:

>> status

The basics of the SDEM algorithm, used in DISC, is described in section 1, page3.

5 Data analysis in MatlabA number of preconfigured visualization methods are featured in show.m. Itshows a figure of the particle assemblage, created on base of the data from a spe-cific output-file. This output file is selected with the command show(’file’,#),where the second parameter is the number of the output file (the numberingstarts from zero (0)). Even though the SDEM calculations (./start-script)have not been completed, the latest output file can be visualized in Matlab, aslong as at least one output-file has been generated:

>> show ( ' f i l e ' , ' l a t e s t ' )

A series of graphs, including total kinetic energy, dissipation energy, number ofparticles and time steps as functions of time can be displayed with:

>> show ( ' energy ' )

When defining a wall-position as a function of pressure, not velocity, all wallvelocities can be displayed with:

>> show ( ' wal l speed ' )

15

SDEM - DISC 5 DATA ANALYSIS IN MATLAB

And if the wall-position is a function of velocity, not pressure, the wall pressurescan be displayed with:

>> show ( ' wa l l f o r c e ' )

The total accumulated horizontal displacement of the particles:>> show ( ' shea rd i sp ' )

If simulating a shearing motion, it may be desired to create a graph, that showsthe horizontal velocity of each particle. This is done by using the ’veloprofile’-option in show(), for example:

>> show ( ' f i l e ' , ' l a t e s t ' , ' v e l o p r o f i l e ' )

Additional arguments can be used in the show-command, to visualize variousparameters, i.e. pressure or strain for each particle. The colorbar-functionadds a bar explaining the values and colors:

>> show ( ' f i l e ' , ' l a t e s t ' , ' f i e l d ' , ' pre s su r e ' )>> co l o rba r>> show ( ' f i l e ' , ' l a t e s t ' , ' f i e l d ' , ' ep l a s t ' )>> co l o rba r

For displaying the colorbar with a fixed span:>> show ( ' f i l e ' , ' l a t e s t ' , ' f i e l d ' , ' ep l a s t ' , ' c l im ' , [ 0 ; 5 ] )>> co l o rba r

5.1 Exporting plotsThe Matlab function exportplots(mode) is included for automatically plottinga range of output files, and exporting them as image files. It plots the raw DEM-data from the last run experiment with show() and saves the output as imagefiles. Open mfiles/exportplots.m, and check the folder, filename and graphicsformat settings. After saving, call the function in Matlab:

>> exportplots ( )

This creates an image for each output file in the output/ directory, and with thedefault settings, saves them in the folder flic/. During the process, Matlab willdisplay a waitbar, showing the progress. If needed, the export may be haltedby clicking the ’Cancel’ button in the waitbar window. Do not press Ctrl-C;after killing the export this way, a restart of Matlab is needed before repeatingthe command. If, for some reason, the code crashes wile running, the waitbaris forcibly closed by:

>> se t (0 , ' ShowHiddenHandles ' , ' on ' )>> de l e t e ( get (0 , ' Chi ldren ' ) )

16

SDEM - DISC 5.2 Importing data

To export the plots with particles colored according to the elastic plasticity orpressure:

>> exportplots ( ' ep l a s t ' )>> exportplots ( ' pre s su r e ' )

To create a plot over the velocity profile for each output file, and exporting it:>> exportplots ( ' v e l o p r o f i l e ' )

To export all normal-, eplast-, pressure and veloprofiles as images use the com-mand exportall(), which creates a series of images (combi) containing the fourview modes simultaneously:

>> exportall (1 )

When the goal of the export is to create an animation in the avi or mpeg-format, I recommend exporting to the jpeg-format, which can be chosen inexportplots.m. In most video editing software the png-format is only poorly,if at all, supported.

5.2 Importing dataAll parameters and values from the simulation results can be imported into theMatlab workspace. In Matlab, make sure the current folder is the mfiles/directory inside the DISC folder. The DEM structure from the current con-figuration is loaded by DEM = DEMload(), which reads input/DEM.mat. Theresulting variable structure imported into the Matlab workspace, and consistsof a hierarchy of variables, as mapped out in appendix B. While DEMload()loads the initial model setup, the Matlab function DEMloadfnr(fnr) loads par-ticle configurations from output file with number fnr.

The following is a number of examples, showing possible ways to visualizeparticle speed5. The following series of commands loads all particle positionsand creates a three-dimensional plot with speed on the z-axis from output file#25:

>> DEM=DEMloadfnr (25) ;>> x=DEM . particles . position ( : , 1 ) ;>> y=DEM . particles . position ( : , 2 ) ;>> z=sqr t ( DEM . particles . velocity ( : , 1 ) .^2+DEM . particles .←↩

velocity ( : , 2 ) . ^2 ) ;>> plo t3 (x , y , z , ' . ' )

Or as a triangular surface for better visualization; lone points distributed in a3D space, visualized in 2D, are difficult to comprehend visually:

>> tri=delaunay (x , y ) ;>> trisurf ( tri , x , y , z )

5Inspired by: http://geology.wlu.edu/connors/primers/Surfaces_and_Grids_in_Matlab/Surfaces_and_Grids_in_Matlab.htm

17

SDEM - DISC 6 SAVING SIMULATION RESULTS

Or as a (smoothed) surface with interpolated data point values in betweenparticles:

>> res=100; %Reso lut ion in x− and y−d i r e c t i o n>> rangeX=min(x ) : (max(x )−min(x ) ) /res :max(x ) ;>> rangeY=min(y ) : (max(y )−min(y ) ) /res :max(y ) ;>> [ X , Y ]=meshgrid ( rangeX , rangeY ) ;>> Z=gr iddata (x , y , z , X , Y ) ;>> su r f (X , Y , Z )

To make a contour plot of the gridded data:>> resZ=100; %Reso lut ion in z−d i r e c t i o n>> rangeZ=min(z ) : (max(z )−min(z ) ) /resZ :max(z ) ;>> contourf (X , Y , Z , rangeZ ) ;

Combining contours and surfaces:>> hold on>> su r f (X , Y , Z , 'EdgeColor ' , ' none ' , ' FaceColor ' , ' i n t e rp ' , '←↩

FaceLight ing ' , 'phong ' )>> contour3 (X , Y , Z , rangeZ , 'k ' )>> f i g u r e ( g c f )

Another example: Arrow field of particle velocities:>> DEM=DEMloadfnr ( ' l a t e s t ' ) ;>> s=0.02; %Ve loc i ty s c a l i n g f a c t o r>> quiver ( DEM . particles . position ( : , 1 ) , . . .

DEM . particles . position ( : , 2 ) , . . .DEM . particles . velocity ( : , 1 ) ∗s , . . .DEM . particles . velocity ( : , 2 ) ∗s , ' AutoScale ' , ' o f f ' ) ;

>> ax i s ( [ 0 0 . 2 0 0 . 1 1 ] )

6 Saving simulation resultsTo save a particle configuration of a certain output-file of a simulation, use thefollowing command. The first parameter is the number of the output-file thatis saved, and the second parameter is the name of the new configuration file:

>> saveconfig (19 , ' p i l e ' )

The new configuration file can now be used in another simulation.

6.1 Copying particle assemblagesTo clone the particle masses and their configurations from previous simulations,the clone-script is used. The parameters are:(number of vertical clones, number of horizontal clones, infile,outfile). Example:

18

SDEM - DISC 6.1 Copying particle assemblages

>> clone (2 , 3 , ' p i l e ' , ' b i g g e r p i l e ' )

Before running the new model, it is essential to change the positions of thewalls in the model, to accommodate for the new particle assemblages. Opentemplate.m, select the new input file (’biggerpile’ in example) and rescalethe walls to create space for the new configuration. After saving, setup the newmodel for the simulations:

>> template (1 )

Initiate the SDEM calculations with the ’./start’ command as previously ex-plained. This will consolidate the individual assemblages with each other.

19

SDEM - DISC A FOLDER STRUCTURE

Appendix

A Folder structureThe root folder is often named after the experiment id. Sub directory and filedescription:

• ’configs/’: Folder for initial particle configurations (.mat-files)• ’flic/’: Folder for image creation plugins (not included)

– ’eps/’: EPS image format directory– ’gif/’: GIF image format directory– ’png/’: PNG image format directory

• ’gmon.out: Unknown• ’go’: Custom script for starting the calculations• ’include/’: Directory for preprocessor-files, included in C source code files.

– ’mylib.c’: C source code for mathematical functions, e.g. matrix opera-tions.

– ’nrutil.c’: Numerical Recipes. Contains among other things the followingfunctions, used for initializing and freeing variables in disc.c:long ∗ divector ( long nl , long nh )/∗ a l l o c a t e a long vec to r with sub s c r i p t range v [ n l . . nh ]←↩

∗/

double ∗ dvector ( long nl , long nh )/∗ a l l o c a t e a double vec to r with sub s c r i p t range v [ n l . .←↩

nh ] ∗/

double ∗∗ dmatrix ( long nrl , long nrh , long ncl , long nch )/∗ a l l o c a t e a double matrix with sub s c r i p t range m[ n r l . .←↩

nrh ] [ nc l . . nch ] ∗/

void free_divector ( long ∗v , long nl , long nh )/∗ f r e e a long vec to r a l l o c a t e d with d i v e c t o r ( ) ∗/

void free_dvector ( double ∗v , long nl , long nh )/∗ f r e e a double vec to r a l l o c a t e d with dvector ( ) ∗/

void free_dmatrix ( double ∗∗m , long nrl , long nrh , long ←↩ncl , long nch )

/∗ f r e e a double matrix a l l o c a t e d by dmatrix ( ) ∗/

– ’nrutil.h’: Numerical recipes header file.– ’random.c’: Contains the function ran0(...) that returns a random number.

• ’input/’: Initial setup for simulations, made by the Matlab functions.

– ’DEM.mat’: Matlab variable structure (see appendix B), containing the ini-tial setup before running the simulation. The file is written by write() inMatlab, which is called at the end of template.m.

– ’grid.dat’: Grid properties, written by write() in Matlab. The first linecontains the x- and y-coordinates of the lower left corner of the grid (theorigo). Second line contains the grid width and height, and the third linethe number of horizontal- and vertical grid boxes.

20

SDEM - DISC

– ’particles.dat’: Particle data, written by write() in Matlab. The firstline contains the number of particles (np). Each following line contains aseries of values for the following variables, space separated:1. x[i][1]2. x[i][2]3. velo[i][1]4. velo[i][2]5. pressure[i]6. stressdev[i][1]7. stressdev[i][2]8. stressdev[i][3]9. radius[i]

10. mass[i]11. cohesion[i]12. fc[i]13. eplast[i]14. bc[i]15. prevelo[i][1]16. prevelo[i][2]17. vflag[i]18. pflag[i]19. visc[i]

– ’patch.dat’:– ’rmode.dat’: Input parameters, set with template(), and written by write()

in Matlab. Each line contains a variable in SI-units:1. gravity, Gravitational acceleration2. young, Young’s modulus3. poisson (set in setup() and startconfig())4. rollres[1]5. rollres[2]6. softening[1]7. softening[2]8. softening[3]9. softening[4]

10. softening[5]11. softening[6]12. softening[7]13. total_time14. filedt15. dt16. fixpatch17. dtcontrol18. minmass19. periflag20. sedi21. Np

21

SDEM - DISC A FOLDER STRUCTURE

22. fcsedi23. cohesionsedi24. denssedi25. sedisurf26. nws27. nscity28. nsblock29. bpress(1,:)30. bpress(2,:)31. bpress(3,:)32. bpress(4,:)

– ’walls.dat’: Input parameters, set with template(), and written by write()in Matlab. Each line contains a variable in SI-units:1. nw, Number of walls ([i])2. walls[i][j], Position of walls3. wallspeed[i][j], Speed of walls4. wallpress[i][j], Pressure of walls5. wallprate[i][j], Pressure rate of walls6. wfric[i], Friction of wall surface7. wfree[i], Enabling free movement of walls

• ’mfiles/’: Files which contain functions available to Matlab.

– ’basicsetup.m’: basicsetup(1) creates particles in grid-like arrangement.The number of particles and the density is specified, as well as the modelheight/width. Calling the function creates a .mat-file in the configs/-folder.

– ’boxit.m’: boxit(fnr) shows the internal pressure of each grid-box.– ’circle.m’: [xc,yc] = circle(x,y,r,np). Creates a circle with center

coordinates (x,y), radius r, and np points in the perimeter. These pointsare returned as (xc,yc).

– ’clone.m’: clone(ny,nx,fn,fout) clones the particle assemblage a specificnumber of times in the y- and x-direction, and outputs the new assemblageto a .mat-file in the configs/-folder.

– ’column.m’: DEM = column(DEM,dcy) is used for vertical matflag-layering,where the second argument specifies the layer width.

– ’combineplots.m’: combineplots() merges all numbered normal-, eplast-, pressure- and veloplot-images from a directory (path set in the file)into a single image, called combi#.

– ’consolidate.m’: consolidate(pressure,1) consolidates a particle as-semblage, by exerting a pressure (pressure) from the upper wall down-wards. If pressure = 0, the assemblage consolidates only under the in-fluence of gravity. The applied particle properties are φ = 5◦ and C = 0Pa.

– ’cut.m’: cut(fn1,fn2) loads the particle configuration with filename fn1from the configs/ folder, selects specific particles, and saves a new configfrom the selected particles as fn2.mat in the configs/ folder.

– ’DEMload.m’: DEM = DEMload() reads and returns DEM structure from theinitial configuration.

22

SDEM - DISC

– ’DEMloadfnr.m’: DEM = DEMloadfnr(fnr) reads and returns DEM struc-ture from a desired configuration.

– ’exportall.m’: exportall(combi) exports all modes of plots. Callingexportall(1) merges the plots to a single image afterwards. In addi-tion it saves the velocity profile, kinetic energy plot, wall speed plot, wallforce plot, wall position plot and the shear displacement plot as images.

– ’exportplots.m’: exportplots(mode) plots the raw DEM-data from thelast run experiment with SHOW() and saves the output as image files.The mode can be normal, eplast, pressure or veloprofile.

– ’getporosity.m’: porosity=getporosity(tri,x,radius) calculates theinter-particle porosity from a triangularization (tri) of particles x in aradius (radius).

– ’layer.m’: DEM = layer(DEM,dcy) is used for horizontal matflag-layering,where the second argument specifies the layer width.

– ’makeconfig.m’: Old function for creating particle configurations.– ’makemesh.m’: function [COORD,TOPO,MAT,BOUND] = makemesh(...) re-

turns mesh matrices COORD, TOPO vector MAT and cell array boundfor a two-dimensional triangular mesh.

– ’mdos/’: PC binaries (MSDOS) for mesh- and triangle calculations in makemesh.m.– ’munix/’: UNIX binaries for mesh- and triangle calculations in makemesh.m.– ’newconfig.m’: Old function for creating particle configurations.– ’plotmethod2.m’: [tri] = plotmethod2(x,radius) triangulates the par-

ticles, and checks wether they are within the critical strain limit. The validtriangles are returned.

– ’saveconfig.m’: SAVECONFIG(filenr,name) saves configuration file fromoutput file number ’filenr’. The name (without extension) of the configu-ration file is given by string ’name’.

– ’scale.m’: scale(fn1,fn2,fac) multiplies the coordinates, pressures, radiiand walls from configs/fn1.mat with the value fac, and saves the resultas configs/fn2.mat.

– ’sdis.m’: sdis(fnr) plots the differential stress versus pressure of theoutput file fnr, like seen in Egholm (2007), figure 7.

– ’setup.m’: The standard physical values for the model, that can be changedwith template.m.

– ’show.m’: show() plots the DEM output. show(’file’,n) plots the parti-cle configuration as it appears in output file n.show(’file’,’latest’) uses latest output file. show(’file’,n,’field’,’pressure’)uses particle pressure as color code, while show(’file’,n,’field’,’eplast’)shows accumulated plastic strain, and show(’file’,n,’field’,’cohesion’)uses particle cohesion. Other types:

∗ x = DEM.particles.position;∗ velo = DEM.particles.velocity;∗ pressure = DEM.particles.pressure;∗ stressdev = DEM.particles.stressdev;∗ eplast = DEM.particles.eplast;∗ density = DEM.particles.density;∗ mass = DEM.particles.mass;

23

SDEM - DISC A FOLDER STRUCTURE

∗ cohesion = DEM.particles.cohesion;∗ friction = DEM.particles.friction;∗ fixflag = DEM.particles.fixflag;∗ prevelo = DEM.particles.prevelo;

– ’startconfig.m’: Outdated function for setting up configurations.– ’starter.m’: starter(DEM) starts the DISC simulation on the local com-

puter using the setup contained inside the DEM structure. This script willonly work on UNIX computers.

– ’status.m’: status() writes status of current model run, by reading datafrom status.dat.

– ’template.m’: template(1) reads a configuration file, applies walls andtheir rules, sets physical parameters, and is used for coloring. This scriptis run just before the DEM-calculations are started.

– ’traceparticle.m’: traceparticle follows a particle through a series ofoutput files. The particle number and output-file range is specified insidethe script. The results (x-, and y-position, x- and y-velocity, total velocity,and number of neighbors) is output both to the screen, and to a text-filein the mfiles/ folder, named after the particle number.

– ’triconfig.m’: triconfig creates randomly located points, and createsparticles without overlap, centered at these points. This script is not usedanywhere.

– ’update.m’: DEM = update(DEM) should be called when e.g. densities arechanged in the particle structure DEM. In this particular case a call toUPDATE(DEM) is needed because particle masses depend on densities.Other dependencies exist between particle or wall positions and the grid.It is strongly advised to call UPDATE(DEM) every time a change in theDEM structure is made.

– ’write.m’: write(DEM) saves the DEM structure to the DISC input filesrmode.dat, particles.dat, walls.dat, patch.dat and grid.dat.

• ’newgo’: Custom script for starting the calculations• ’output/’: Folder containing output .dat-files, monitor.dat and logfile.txt.

monitor.dat contains a line for each output file, with the following information(space seperated):

1. time: Simulation time2. Ekin: Total kinetic energy3. Erot: Total rotational energy4. Ediss: Total dissipation energy5. wallspeed[1][1]: Lower wall horizontal velocity.6. wallspeed[1][2]: Lower wall vertical velocity.7. wallforce[1][1]-wallpress[1][1]: Lower wall horizontal force.8. wallforce[1][2]-wallpress[1][2]: Lower wall vertical force.9. wallspeed[2][1]: Upper wall horizontal velocity.

10. wallspeed[2][2]: Upper wall vertical velocity.11. wallforce[2][1]-wallpress[2][1]: Upper wall horizontal force.12. wallforce[2][2]-wallpress[2][2]: Upper wall vertical force.

24

SDEM - DISC

13. avs1: Average stress14. avs2: Average stress15. avp: Average pressure16. np: Number of particles17. dt: Time step length for calculations

For each output time-step, a new breaklist#.dat, output#.dat and walls#.datis created, where # is the output time step number.Each walls#.dat-file contains the coordinates of the endpoints of the walls.Each output#.dat-file contains information about all individual particles; eachparticles represented by a line, and the following data (space separated):

1. X-axis coordinate of particle center (x[i][1])2. Y-axis coordinate of particle center (x[i][2])3. X-axis velocity (velo[i][1])4. Y-axis velocity (velo[i][2])5. Pressure (pressure[i])6. Stressdev (stressdev[i][1])7. Stressdev (stressdev[i][2])8. Stressdev (stressdev[i][3])9. Plastic deformation (eplast[i])

10. Angular velocity (rotation[i])11. Broken (br[i], 0 = No, 1 = Yes)12. Birthday (bday[i]). Only useful if particles are added during the simula-

tion.13. Radius (radius[i])14. Sliding (sqrt(srate[i][1]*srate[i][1]+srate[i][2]*srate[i][2]

+2.0*srate[i][3]*srate[i][3])))15. Accumulated x-axis displacement (xdisp[i])

• ’source/’: Folder with source code, compiled binaries and compile-script for theDEM software.

• ’start’: Standard script for starting the DEM calculations. The contents offlic/ and output/ are flushed, then disc is started with: ’$PWD/source/disc$PWD &’. DISC runs in the background, so closing the session will not halt thesimulation.

• ’status.dat’: File showing the completed calculation progress in percentage,and time steps.

25

SDEM - DISC B DEM PARAMETER STRUCTURE IN MATLAB

B DEM parameter structure in MATLABThe DEM structure from the current configuration is loaded into MATLABby the command DEM = DEMload(), which reads the file input/DEM.mat. Theresulting variable structure imported into the Matlab workspace is the following:

DEM. fixpatch. nfppositionvelocity

grid. heightnxnyorigowidth

particles. cohesiondensityeplastfixflagfrictionmassmatflagnppflagpositionpressurepreveloradiusstressdevvelocityvflagvisc

rm. bpresscohesionsedidenssedidtdtcontrolfcsedifiletimefixpatchgravityminmassnblockncityNpnwsperiflagpoissonrollressedisedisurfsofteningtotaltimeyoung

walls. freefrictionnwpositionpratepressurevelocity

26

SDEM - DISC

C Sample: template.m for shear-test

1 func t i on template ( fg )23 c l o s e a l l ;45 DEM = setup ( ' s t e s t ' ) ; %%Config f i l e67 l = 0 ; r = 0 . 5 ;8 d = 0 ; u = 1 . 0 ;9

10 %%Four wa l l s11 %DEM. wa l l s . p o s i t i o n = [ l , d , l , u ; . . .12 % r , d , r , u ; . . .13 % l , d , r , d ; . . .14 % l , u , r , u ] ;1516 %%Two wa l l s17 DEM . walls . position = [ l , d , r , d ; . . .18 l , u , r , u ] ;192021 DEM . walls . velocity = [ 0 , 0 ; . . .22 0 , 0 ] ;2324 periflag = 1 ; %1 f o r p e r i o d i c boundaries , 0 f o r normal25 g = 9 . 8 1 ; %Grav i t a t i ona l a c c e l e r a t i on , [m/( s ^2) ]2627 %%Mater ia l parameters28 phi = 35 ; %Angle o f i n t e r n a l f r i c t i o n , [ Deg ]29 C = 10 ; %Cohesion , [ Pa ]3031 %%E f f e c t i v e normal pres sure , [ Pa ]32 p_e = 30e3 ;3334 %%Shear s t r ength accord ing to the Coulomb−p l a s t i c deformation law←↩

:35 tau_u = C + p_e ∗ tand ( phi ) ;363738 %%Graphical output39 d i sp ( [ ' Shear s t r ength : tau_u = ' num2str ( tau_u ) ' Pa ' ] ) ;4041 %%Fixed shea r ing v e l o c i t y42 vel = 0 . 1 ; %Shear ing ve l o c i t y , [m/ s ]4344 DEM . walls . friction = [ 1 , 1 ] ;45 DEM . walls . free = [ 0 , 1 ] ;46 DEM . walls . pressure = zero s (2 , 2 ) ;47 DEM . walls . pressure ( 2 , 2 ) = −p_e ;4849 DEM . walls . prate = zero s (2 , 2 ) ;5051 %%Number o f p a r t i c l e s52 np = DEM . particles . np ;5354 %%Color v e r t i c a l columns55 DEM = column ( DEM , 0 . 0 5 ) ;565758 %Fix the ho r i z on t a l v e l o c i t y o f two l a y e r s59 i f periflag == 1 ,

27

SDEM - DISC C SAMPLE: TEMPLATE.M FOR SHEAR-TEST

6061 DEM . rm . periflag = 1 ; %Per i od i c boundary cond i t i on s6263 y = DEM . particles . position ( : , 2 ) ;6465 %Bottom lay e r : Hor i zonta l v e l o c i t y zero .66 I = f ind ( y < 0 .01 ) ;67 DEM . particles . matflag ( I ) = 3 ;68 DEM . particles . fixflag ( I ) = 1 ;69 DEM . particles . prevelo (I , 1 ) = 0 . 0 ;70 DEM . particles . prevelo (I , 2 ) = 0 . 0 ;7172 %Top l ay e r : Hor i zonta l v e l o c i t y f i x ed .73 I = f ind ( y > 0 .25 ) ;74 DEM . particles . matflag ( I ) = 3 ;75 DEM . particles . fixflag ( I ) = 1 ;76 DEM . particles . prevelo (I , 1 ) = vel ;77 DEM . particles . prevelo (I , 2 ) = 0 . 0 ;787980 %move the top wal l to i n i t i a l p o s i t i o n81 top = max( y+DEM . particles . radius ) ;82 DEM . walls . position ( 2 , 2 ) = top ;83 DEM . walls . position ( 2 , 4 ) = top ;84 end8586 %DEM = laye r (DEM, 0 . 1 ) ;87 DEM . particles . density = 1900∗ ones ( np , 1 ) ;88 DEM . particles . friction = tan ( phi∗ pi /180) ∗ones ( np , 1 ) ;89 DEM . particles . cohesion = C∗ones ( np , 1 ) ;90 DEM . rm . young = 1e10 ;91 DEM . rm . dt = 4.0 e−7;92 DEM . rm . filetime = 1.0 e−2; %Output i n t e r va l , [ Hz = 1/ s ] . 2 . 0 e−02 =←↩

50 fp s93 DEM . rm . totaltime = 5 . 0 ; %Total time , [ s ]94 DEM . rm . gravity = g ; %Grav i t a t i ona l a c c e l e r a t i on , [m/( s ^2) ]95 DEM . rm . rollres (1 ) = 1e2 ;96 DEM . rm . rollres (2 ) = 1e10 ; %tan (60∗ pi /180) ;97 DEM . rm . softening (1 ) = 1 .0 e−1;98 DEM . rm . softening (2 ) = 1 .0 e−0;99 DEM . rm . softening (3 ) = 1 .0 e−0;100 DEM . rm . softening (4 ) = 1 .0 e−2;101 DEM . rm . softening (5 ) = 1 .0 e−1;102 DEM . rm . softening (6 ) = 1 .0 e−0;103 DEM . rm . softening (7 ) = 0 .1 e−0;104 DEM . rm . fixpatch = 0 ;105 DEM . rm . sedi = 0 ;106 DEM . rm . sedisurf = 0 . 3 ;107 DEM . rm . nws = 4 ;108109 DEM = update ( DEM ) ;110111 write ( DEM ) ;112113 i f fg ,114 show ( ' f i e l d ' , 'mat ' , 'method ' , 1 , ' g r id ' , 1 ) ;115 end ;

28

SDEM - DISC REFERENCES

ReferencesD.L. Egholm. A new strategy for discrete element numerical models. 1. theory.

J. Geophys. Res., 112(B05203):doi:10.1029/2006JB004557, 2007.

D.L. Egholm, M. Sandiford, O.R. Clausen, and S.B. Nielsen. A new strategyfor discrete element numerical models. 2. sandbox applications. J. Geophys.Res., 112(B05204):doi:10.1029/2006JB004558, 2007.

S.W. Smith, C.K. Hall, and B.D. Freeman. Molecular dynamics for polymericfluids using discontinuous potentials* 1. Journal of Computational Physics,134(1):16–30, 1997.

— End of file —

29