Attributes and Properties

Introduction

Note

The project file for this example may be viewed/run in PFC.[1] The data files used are shown at the end of this example.

The distinction between an attribute and a property is central to command processing and plotting.

• Attributes are intrinsic characteristics of model components such as position, velocity, size, etc. The list of attributes is unchanging. Bodies (balls, clumps, and walls), pieces (balls, pebbles, and facets) and contacts have attributes. See the ball attribute, clump attribute, and wall attribute documentation for lists of modifiable attributes. Attributes can also be listed in PFC with the ball list attribute, clump list attribute, and wall list attribute commands.
• Properties apply exclusively to pieces and are lists of string/value pairs specified by the user. By default, pieces are devoid of properties. These string/value pairs are meant to represent the surface conditions of the pieces and may be used by contact models to determine how pieces interact.

Mistaken Property Assignment

The proper assignment of attributes and properties is very important. The following example demonstrates a common pitfall: a select range of balls is assigned a nonzero velocity in the \(x\)-direction using the ball attribute command, while a new property with name velocity-x and a value of 1.0 is assigned to the remaining balls via the ball property command. Since velocity-x can refer to a keyword of the ball attribute command, a warning occurs.

; fname: attributes_and_properties.dat (3D)
;
;  Demonstrate the distinction between ball attributes and ball properties
;==============================================================================
model new
model large-strain on
model title 'Attributes and Properties'

; generate a loose assembly of balls 
model domain extent -10.0 10.0
model random 10001
ball generate number 10 radius 0.5 box -0.5 0.5 -0.5 0.5 -9.0 9.0

; set a nonzero x-velocity to part of the balls 
ball attribute velocity-x 1.0 range position-z -10.0  0.0

; create a property with name 'xvelocity' to the other balls 
ball property 'velocity-x' 1.0 range position-z   0.0 10.0

; set density and cycle - note that only part of the balls actually moved 
ball attribute density 1.0
model mechanical timestep fix 1e-2
model solve time 2

program return
;==============================================================================
; eof: attributes_and_properties.dat (3D)

Ten balls are created in a column. The top five balls are assigned the velocity-x property, while the velocity attribute of the bottom five balls is modified. A fixed timestep is set, and the model is solved for a specified time interval. Figure 1 shows the final state of the system with balls and ball velocity arrows plotted (see the Ball Plot Item for plotting details). Balls are colored by their velocity-x property. The bottom five balls are not rendered since they have no velocity-x property. On the other hand, no arrows are rendered for the top five balls, since no velocity has been assigned to these balls. As a result, the balls with the property assignment do not move once cycling begins.

Figure 1: Final state of the system.

Property Assignment for Contact Inheritance

The following example illustrates the intended use of the property concept, namely for contact model property assignment.

; fname: properties_in_contacts.dat
;
;  Demonstrate ball properties being used to set contact model properties
;=============================================================================
model new
model large-strain on
model title 'Properties in Contacts'

; create the domain
model domain extent -10.0 10.0 -5.0 5.0 -10.0 10.0 condition reflect

; use the linear contact model 
contact cmat default model linear

; generate an assembly
model random 10001
ball generate number 140 radius 1.0 box -10 0 -5 5 -10 10 tries 300000
ball generate number 140 radius 1.0 box 0 10 -5 5 -10 10 tries 300000

; assign the density and local damping
ball attribute density 1000 damp 0.7

;set gravity
model gravity 10

; assign properties balls for the linear contact model to use
ball property 'kn' 1e8 range position-x -10 0
ball property 'kn' 5e5 range position-x 0 10
ball property 'fric' 0.7

; put a partition between the two sides
wall generate plane dip 90 dip-direction 90
wall property 'kn' 1e7

; let them drop
model solve time 10

program return
;=============================================================================
; eof: properties_in_contacts.dat

In this case, equal numbers of balls are generated on either side of a wall partition. The linear contact model is assigned as the default contact model for all contact types (see the contact cmat default command), but no properties are specified in the CMAT. Instead, the ball property command is used to assign the surface property kn to balls on either side of the partition. Note that balls on the left have 200 times higher kn values than balls on the right. The linear contact model supports inheritance where contact model properties are determined from piece properties. The linear contact model documentation discusses the details of inheritance for this contact model. As the final configuration reveals, there is significantly more compaction on the right side under the force of gravity as a result of less-stiff interactions between the balls.

Figure 2: System where contact model properties are assigned from ball properties.

Discussion

This tutorial demonstrates the differences between attributes and properties. These differences are central to command processing and plotting in PFC.

Data Files

attributes_and_properties.dat (3D)

; fname: attributes_and_properties.dat (3D)
;
;  Demonstrate the distinction between ball attributes and ball properties
;==============================================================================
model new
model large-strain on
model title 'Attributes and Properties'

; generate a loose assembly of balls 
model domain extent -10.0 10.0
model random 10001
ball generate number 10 radius 0.5 box -0.5 0.5 -0.5 0.5 -9.0 9.0

; set a nonzero x-velocity to part of the balls 
ball attribute velocity-x 1.0 range position-z -10.0  0.0

; create a property with name 'xvelocity' to the other balls 
ball property 'velocity-x' 1.0 range position-z   0.0 10.0

; set density and cycle - note that only part of the balls actually moved 
ball attribute density 1.0
model mechanical timestep fix 1e-2
model solve time 2

program return
;==============================================================================
; eof: attributes_and_properties.dat (3D)

properties_in_contacts.dat (3D)

; fname: properties_in_contacts.dat
;
;  Demonstrate ball properties being used to set contact model properties
;=============================================================================
model new
model large-strain on
model title 'Properties in Contacts'

; create the domain
model domain extent -10.0 10.0 -5.0 5.0 -10.0 10.0 condition reflect

; use the linear contact model 
contact cmat default model linear

; generate an assembly
model random 10001
ball generate number 140 radius 1.0 box -10 0 -5 5 -10 10 tries 300000
ball generate number 140 radius 1.0 box 0 10 -5 5 -10 10 tries 300000

; assign the density and local damping
ball attribute density 1000 damp 0.7

;set gravity
model gravity 10

; assign properties balls for the linear contact model to use
ball property 'kn' 1e8 range position-x -10 0
ball property 'kn' 5e5 range position-x 0 10
ball property 'fric' 0.7

; put a partition between the two sides
wall generate plane dip 90 dip-direction 90
wall property 'kn' 1e7

; let them drop
model solve time 10

program return
;=============================================================================
; eof: properties_in_contacts.dat

attributes_and_properties.dat (2D)

; fname: attributes_and_properties.dat (2D)
;
;  Demonstrate the distinction between ball attributes and ball properties
;==============================================================================
model new
model large-strain on
model title 'Attributes and Properties'

; generate a loose assembly of balls 
model domain extent -10.0 10.0
model random 10001
ball generate id 1 10 box -1.0 1.0 -10.0 10.0

; set a non-zero velocity-x to part of the balls 
ball attribute velocity-x 1.0 range position-y -10.0  0.0

; create a property with name 'xvelocity' to the other balls 
ball property 'xvelocity' 1.0 range position-y   0.0 10.0

; set density and cycle - note that only part of the balls actually moved 
ball attribute density 1.0
model mechanical timestep fix 1e-5
model cycle 10

program return
;==============================================================================
; eof: attributes_and_properties.dat (2D)

Endnotes

[1]	To view this project in PFC, use the program menu. Help ▼ Examples…   ⮡   PFC     ⮡   Tutorials       ⮡   AttributesAndProperties         ⮡   AttributesAndProperties.prj