Y2D Manual

The following manual has been prepared by Prof. A. Munjiza and should be of great help for the users of this program. You can also download a PDF version of this manual here.

INTRODUCTION

Y is a combined finite-discrete element method program designed for the purpose of demonstrating some of the concepts explained in the book entitled The Combined Finite-Discrete Element Method, by A.Munjiza.

The Copyright (C) 2000, to this program (Y program) and source code supplied with it belongs to Dr. A. Munjiza This code is provided as part of the book entitled "The Combined Finite Discrete Element Method". It is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Inclusion of a part or whole of this code into any other commercial or research or other purpose code is not granted without author's written explicit permission. When results using whole or any part of this code are published, acknowledgement to the author should be made.

Source code is also provided, however you cannot use it unless you agree with the following:

1)      Copyright (C) 2000, Dr. Antonio Munjiza

2)      This code is provided as part of the book entitled "The Combined Finite Discrete Element Method".

3)      It is distributed WITHOUT ANY WARRANTY;without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A  PARTICULAR PURPOSE.

4)      Inclusion of a part or whole of this code into any other commercial or research or other purpose code is not granted without author's written explicit permission.

5)      When results using whole or any part of this code are published, Y code must be mentioned and acknowledgement to Dr Munjiza must be made.

6)      Should you modify this source code, the Copyright (C) on the modified code as a whole belongs to Dr. A. Munjiza regardless of the extent or nature of modifications.

7)      Copyright (C) to whole of any code containing any part of this code also belongs to Dr. A.Munjiza.

8)      Any code comprising any part of this source code must be called Y program.

9)      If you do not agree with these, you are not allowed to do any modifications to any part of this source code or include any part of it in any other program.

INPUT FILE

Data convention:

1)            Variables names starting with M and N are integer numbers indicating maximum and actual size of arrays used to construct the incore database.

2)            Variables names starting with I are integer numbers.

3)            Variables names starting with D are double numbers.

4)            Variables names starting with D1 and I1 indicate one dimensional array of double and integer numbers respectively.

5)            Variables names starting with D2 and I2 indicate two dimensional array of double and integer numbers respectively.

 

One dimensional arrays:

A one dimensional array I1ANYARRAY[10] comprising of 10 integer numbers is supplied in an input file as follows:

/YD/YDE/I1ANYARRAY 10

1 2 3 4 5 6 7 8 9 0

where 10 indicates that the name is followed by 10 integer numbers. I1ANYARRAY[0] to I1ANYARRAY[9].

In a similar way a one dimensional array of double numbers D1ANYARRAY[10] is supplied in an input file as follows:

/YD/YDE/D1ANYARRAY 10

0.1  0.2  0.3  0.4  0.5  0.6  0.7  0.8  0.9  0.0

where 10 indicates that the name is followed by 10 double numbers. D1ANYARRAY[0]=0.1 to D1ANYARRAY[9]=0.0

 

Two dimensional arrays:

A two dimensional array I2ANYARRAY[2][5] comprising of two rows and five columns is supplied in an input file as follows:

/YD/YDE/I2ANYARRAY 12   2   5

1   2   3   4   5

21 22 23 24 25

where 12 indicates that the arrays is read row by row (i.e. the rightmost index rotates faster than the leftmost index). Thus I2ANYARRAY[0][0]=1, I2ANYARRAY[0][1]=2, I2ANYARRAY[0][2]=3, etc. Also I2ANYARRAY[1][0]=21, I2ANYARRAY[1][1]=22, etc.

Alternatively the same array can be written as follows:

/YD/YDE/I2ANYARRAY 21   2   5

1   21

2   22

3   23

4   24

5   25

The first number following the name is 21 which indicates that index 1 (the leftmost index) rotates fastest and index 2 (the rightmost index) rotates slowest. Thus I2ANYARRAY[0][0]=1, I2ANYARRAY[0][1]=2, I2ANYARRAY[0][2]=3, etc. Also I2ANYARRAY[1][0]=21, I2ANYARRAY[1][1]=22, etc.

Names of all the variables must be present in the input file (data need not be supplied for variables printed in italic) as shown in the following table:

Control Database

VARIABLE DESCRIPTION
/* comment */ Anything between /* and */ is ignored, i.e. is considered as a comment (do not forget to put space before and after the */)
/YD/YDC/MCSTEP Maximum number of time steps
/YD/YDC/NCSTEP Actual number of time steps (cannot be greater than /YD/YDC/MCSTEP)
/YD/YDC/DCGRAY Acceleration of gravity (in y direction)
/YD/YDC/DCSIZC Maximum size of coordinate in any direction (size of physical space – corresponding outputs are normalized using this value)
/YD/YDC/DCSIZF Maximum size of force in any direction (corresponding outputs are normalized using this value)
/YD/YDC/DCSIZV Maximum size of velocity in any direction (corresponding outputs are normalized using this value)
/YD/YDC/DCSTEC Size of the time step (see in the book how to calculate critical-maximum time step)
/YD/YDC/DCTIME Current time. i.e. time at start of this run.
/YD/YDC/ICOUTF Output frequency – every so many time steps complete state of the system is recorded in a file with extension .ym which can be visualized using M program, which is FEM/DEM Visualizer accompanying Y program.
/YD/YDC/ICOUTI Serial number of first output associated with this run.
/YD/YDC/ICOUTP Number of characters for each number in output file (for example: three characters is equivalent to six significant digits)

Element Database

/YD/YDE/MELEM Maximum number of finite elements (with fracture the actual number of finite elements increases during the run, however, it should not exceed this number)
/YD/YDE/NELEM Actual number of finite elements at the beginning of this run.
/YD/YDE/MELST Maximum number of state variables per finite element.
/YD/YDE/NELST Actual number of state variables per finite element.
/YD/YDE/MELNO Maximum number of nodes per finite element.
/YD/YDE/NELNO Actual number of nodes per finite element.
/YD/YDE/D2ELST [MELST][MELEM] array containing state variables for all finite elements.
/YD/YDE/I1ELCF Head of a list of contacting couples for each finite element.
/YD/YDE/I1ELPR Set of properties associated with each element.
/YD/YDE/I2ELTO [MELNO][MELEM] topology array containing nodes for each finite element.

Interaction Database

/YD/YDI/MICOUP Maximum number of contacting couples of finite elements.
/YD/YDI/NICOUP Actual number of contacting couples of finite elements (always set to zero)
/YD/YDI/IIECFF Internal variable used for contact (always set to -2)
/YD/YDI/DIEDI Internal variable (travel since last detection) used to trigger contact detection (always set to a large number in order to trigger contact detection immediately at the start of this run)
/YD/YDI/DIEZON Size of the buffer around each finite element for contact detection purposes (usually 1/5 of the size of the smallest finite element)
/YD/YDI/D1IESL [MELEM] array used to store sliding distance between couples in contact (usually set to zero)
/YD/YDI/I1IECN [MICOUP] array used to store next contacting couple in the list.
/YD/YDI/I1IECT [MICOUP] array used to store target finite element for each contacting couple.


Node Database

/YD/YDN/MNODIM Maximum number of degrees of freedom per node (usually 2 in 2D)
/YD/YDN/NNODIM Actual number of degrees of freedom per node (usually 2 in 2D)
/YD/YDN/MNOPO Maximum number of nodes.
/YD/YDN/NNOPO Actual number of nodes.
/YD/YDN/D2NCC [MNODIM][MNOPO] array containing the current coordinates of the nodes.
/YD/YDN/D2NCI [MNODIM][MNOPO] array containing the initial coordinates of the nodes (usually corresponding to undeformed system)
/YD/YDN/D2NFC [MNODIM][MNOPO] array containing the current nodal forces.
/YD/YDN/D1NMCT [MNOPO] array containing the current mass for each node.
/YD/YDN/D2NVC [MNODIM][MNOPO] array containing the current velocities for each node.
/YD/YDN/I1NOBF [MNOPO] array containing a flag indicating that a node is on the boundary (usually set to 1 for all nodes indicating the boundary. Any node with the flag set to zero is considered not to be on the boundary)
/YD/YDN/I1NOPR [MNOPO] array containing an ID of a property set associated with each node.

Borehole Database

/YD/YDB/MBORH Maximum number of boreholes
/YD/YDB/NBORH Actual number of boreholes
/YD/YDB/MBDIM Maximum number of dimensions of boreholes
/YD/YDB/NBDIM Actual number of dimensions of boreholes
/YD/YDB/NBPF Number of amplitude factors
/YD/YDB/D2BCIA [MBDIM][MBORH] coordinates of point A in borehole
/YD/YDB/D2BCIB [MBDIM][MBORH] coordinates of point B in borehole
/YD/YDB/D1BRAD [MBORH] radii of boreholes
/YD/YDB/D1BPF [NBPF] amplitude factor of pressure amplitude
/YD/YDB/D1BTS [MBORH] start time of pressure load on boreholes
/YD/YDB/D1BTE [MBORH] end time of pressure load on boreholes
/YD/YDB/D1BVDET [MBORH] velocity of detonation on boreholes
/YD/YDB/DBPR Amplitude of pressure applied on boreholes
/YD/YDB/DBBUF Buffer (maximum size of element)
/YD/YDB/DBLMAX Maximum length of boreholes

Output History Database

/YD/YDO/MOHYS Maximum number of history variables.
/YD/YDO/NOHYS Actual number of history variables.
/YD/YDO/DOHYP Output history accuracy.
/YD/YDO/D1OHYF [MOHYS] output history factor to scale state.
/YD/YDO/D1OHYC [MOHYS] output history factor to scale time.
/YD/YDO/D1OHYS [MOHYS] output history state.
/YD/YDO/D1OHYT [MOHYS] output history time.
/YD/YDO/D1OHYX [MOHYS] output history x coordinate of the point.
/YD/YDO/D1OHYY [MOHYS] output history y coordinate of the point.
/YD/YDO/D1OHYZ [MOHYS] output history z coordinate of the point.
/YD/YDO/I1OHYT [MOHYS] output history type, i.e. which variable:

0 – default (nothing)                                 11 – isotropic elastic damage

1 – stress σxx                                              12 – borehole mass

2 – stress σxy                                              13 – borehole pressure

3 – stress σyy                                              14 – borehole spec. volume

7 – velocity                                                15 – total kinetic energy

8 – velocity x                                             16 – G2 pressure

9 – velocity y                                             17 – isotropic elastic damage

10 – velocity z

Property Database

/YD/YDP/MPROP Maximum number of properties sets.
/YD/YDP/NPROP Actual number of properties sets.
/YD/YDP/MFACT Maximum number of amplitude factors
/YD/YDP/NFACT Actual number of amplitude factors
/YD/YDP/D3PFAC [2][MPROP][MFACT] array containing for each property series of MFACT times and amplitude factors. Values of D1PNAX, D1PNAY, D1PNAP and D1PNAT are multiplied by amplitude factors at specified times for each property. Input should have the following format (for 3 types of properties):

t1 f1

t1 f1

t2 f2

t2 f2

t3 f3

t3 f3

If array is not specified in input file, default value of amplitude factor in all time steps is 1 (constant force, velocity, pressure etc.).

/YD/YDP/D1PEFS [MPROP] array containing shear strength of material for finite elements for each of the properties.
/YD/YDP/D1PEFT [MPROP] array containing tensile strength of material for finite elements for each of the properties.
/YD/YDP/D1PEGF [MPROP] array containing fracture energy Gf of material for finite elements for each of the properties.
/YD/YDP/D1PEKS [MPROP] array containing viscous damping of material for finite elements for each of the properties (for D1PEKS equal 2h * SQRT(E * density) , finite element smaller than h is critically damped)
/YD/YDP/D1PELA [MPROP] array containing Lamé elastic constant. (l)
/YD/YDP/D1PEMU [MPROP] array containing Lamé elastic constant. (m)
/YD/YDP/D1PEPE [MPROP] array containing penalty term for contact (usually 2 to 100 times greater than lambda)
/YD/YDP/D1PEFR [MPROP] array containing friction (from 0 – glass to 2.5 – rubber).
/YD/YDP/D1PERO [MPROP] array containing density.
/YD/YDP/D1PNAP [MPROP] array containing amplitude of load applied as element surface pressure.
/YD/YDP/D1PNAT [MPROP] array containing amplitude of load applied as element surface traction.
/YD/YDP/D1PNAX [MPROP] array containing amplitude of force or velocity in local x direction for each node.
/YD/YDP/D1PNAY [MPROP] array containing amplitude of force or velocity in local y direction for each node.
/YD/YDP/D1PNXX [MPROP] array containing the x component of x axis of local coordinate system for each node.
/YD/YDP/D1PNXY [MPROP] array containing the y component of x axis of local coordinate system for each node.
/YD/YDP/D1PNYX [MPROP] array containing the x component of y axis of local coordinate system for each node.
/YD/YDP/D1PNYY [MPROP] array containing the y component of y axis of local coordinate system for each node.
/YD/YDP/D1PSEM [MPROP] array containing the maximum tensile stretch.
/YD/YDP/I1PEFR [MPROP] array containing fracture flag. If greater than zero all elements corresponding to this property will be processed as fracturing medium. If it is set to zero for a particular property set, no fracture processing for that property set will take place, i.e. finite elements that are assigned that property will remain non fractured.
/YD/YDP/I1PEJP [MPROP] array containing joint property (if >0 joint)
/YD/YDP/I1PEMB [MPROP] array. If greater than zero boundary nodes are marked, otherwise not.
/YD/YDP/I1PEMN Numbers of successive mesh refinements.

Figure 1. Basic mesh

Figure 2. I1PEMN=1

Figure 3. I1PEMN=11

Figure 4. I1PEMN=2

Figure 5. I1PEMN=22

Figure 6. I1PEMN=21

Figure 7. I1PEMN=321- Introduces joints on element edges thus enabling fracture.

Figure 8. I1PEMN=411- Separates finite elements from each other turning mesh into a heap of fragments interacting with each other.

/YD/YDP/I1PNFX [MPROP] array. 1 indicates that a force is applied to a node in local x direction, 2 indicates that acceleration is applied to a node and 3 indicates that a velocity is applied to a node. For each node actual force, velocity or acceleration is obtained by multiplying amplitude (such as D1PNAX) with factor (such as D1PNAF).
/YD/YDP/I1PNFY [MPROP] array. 1 indicates that a force is applied to a node in local y direction, 2 indicates that acceleration is applied to a node and 3 indicates that a velocity is applied to a node. For each node actual force, velocity or acceleration is obtained by multiplying amplitude (such as D1PNAY) with factor (such as D1PNAF).
/YD/YDP/I1PSDE [MPROP] array containing ID of elastic damage state variable, say zero will indicate that first state variable is elastic damaged, one will indicate that elastic damaged is second state variable, i.e. stored in the second column of the array D2PELST.
/YD/YDP/I1PTYP [MPROP] array containing the type of each property. Indicates type of object to which this property is associated. For instance:

-1 2D mechanical x, y d.o.f. node

1 plane stress elastic triangle

2 rigid triangle

3 joint

4 plain stress softening triangle

$YDOIT It is a command to execute the program.
$YSTOP It is a command to stop the program.

 

Y computer program is a research code. As such it does not make any checks of the input data and will usually crash if the input file is not compiled properly. It is especially sensitive to variables starting with letters M and N, which control dynamic-array- sizes. However, should any of the variables necessary for the processing of the job be missing, memory allocation for that variable may not be performed and a usual result is pointer- type crash. We advise that file generation be taken in stages from the file which runs smoothly. Should the program run for few time steps, it usually finishes whole job. Thus, it is a good idea to run a job for say 10 time steps after every small modification of input file in order to a sort “test” that it is correct. Should variable names be wrong in the input file, all variable names before the wrong one are recorded in the file Ytmp. By looking at this file, one can see what variables Y has accepted.
 

Good luck. Should you have any problems, source code is also provided, however you should not use the source code unless you agree with the following 9 points:

1)      Copyright (C) 2000, Dr. Antonio Munjiza

2)      This code is provided as part of the book entitled "The Combined Finite Discrete Element Method".

3)      It is distributed WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A  PARTICULAR PURPOSE.

4)      Inclusion of a part or whole of this code into any other commercial or research or other purpose code is not granted without author's written explicit permission.

5)      When results using whole or any part of this code are published, Y code must be mentioned and acknowledgement to Dr Munjiza must be made.

6)      Should you modify this source code, the Copyright (C) on the modified code as a whole belongs to Dr. A. Munjiza regardless of the extent or nature of modifications.

7)      Copyright (C) to whole of any code containing any part of this code also belongs to Dr. A.Munjiza.

8)      Any code comprising any part of this source code must be called Y program.

9)      If you do not agree with these, you are not allowed to do any modifications to any part of this source code or include any part of it in any other program.