Custom Properties

EDEMpy allows both reading and writing of custom properties from a deck.

Unlike other EDEMpy writing functionality, this is not limited to the last Time Step since it is used to write post-processed information back into a completed simulation.

There are four different types of custom properties:

deck.particleCustomProperties
deck.geometryCustomProperties
deck.simulationCustomProperties
deck.contactCustomProperties

Contact custom properties are further divided into two sub-types - particle-particle contacts and particle-geometry contacts.

deck.contactCustomProperties.surfSurf deck.contactCustomProperties.surfGeom

Creating Custom properties

You can create properties using the ‘createCustomProperty()’ function:

deck.particleCustomProperties.createCustomProperty(
name="Property Name",
defaultValue=[0.0, 0.0, 0.0], # This would be a 3D property
)

Alternatively, if ‘defaultValue’ is to have the same value repeated for each dimension, the property’s dimensionality can instead be expressed as a number:

deck.particleCustomProperties.createCustomProperty(
name="Property Name",
defaultValue=0.0,
numElements=3, # This is still a 3D property

Reading custom properties

A list of existing properties is available for each property type as ‘customPropertyNames’:

# Returns a list of the names of all particle custom properties
deck.particleCustomProperties.customPropertyNames

The data for a custom property can be obtained as a Numpy array using the ‘getData’ function:

deck.particleCustomProperties.getData(
property="Property Name", # Can alternatively use property ID
tstep=0, # Timestep index
particleType=0, # Must specify a particle type
)

The third parameter has a different meaning for each property type:

Particle: The particle type ID
Geometry: The geometry ID
Simulation: Does not have a third parameter
Contact: Does not have a third parameter

Writing custom properties

Writing data to a custom property is done using ‘setData’ instead of ‘getData’, adding a Numpy array (or list) of the desired data as an additional parameter.

For example:

deck.particleCustomProperties.setData(
   property="Property Name", # Can alternatively use property ID
   tstep=0, # Timestep index
   particleType=0, # Must specify a particle type
   value=[
      # Assuming 3D property and 4 particles
   [0.1, 0.1, 0.1],
   [0.1, 0.1, 0.1],
   [0.1, 0.1, 0.1],
   [0.1, 0.1, 0.1],
   ]
)

Due tothe multi-threaded nature of simulations, the number and ordering of particles will not be the same in each Time Step.

Deleting Custom properties

You can delete properties using ‘deleteCustomProperty’.

# Can alternatively give the property ID instead of the name
deck.particleCustomProperties.deleteCustomProperty("My Property")

Changing properties

Renaming a property

You can rename an existing property.

deck.particleCustomProperties.renameCustomPropertyIndex(
prev_name, # Current name
new_name # New name
)

Changing the order of properties

You can change the order of two properties:

deck.particleCustomProperties.changeCustomPropertyIndex(
old_index,
new_index
)

To get the current index of a property, use the ‘getPropertyIndexForName()’ function:

deck.particleCustomProperties.getPropertyIndexForName("My Property")

Example

The following code creates a particle custom property called “My Property” which starts as 0.0 for each particle and increases by 1 every Time Step while the particle is in the simulation:

import edempy
with edempy.Deck("path_to_deck.dem") as deck:
   particle_type = 0
   prop_name = "My Property"
   properties = deck.particleCustomProperties
   properties.createCustomProperty(
      prop_name,
      0.0, # Default value (scalar)
   )
   for time_id in range(1, deck.numTimesteps):
      # Get current values
      old_data = properties.getData(
         property=prop_name,
         tstep=time_id,
         particleType=particle_type,
      )
      # Add 1
      new_data = old_data + 1.0
      # Write new values
      properties.setData(
         property=prop_name,
         tstep=time_id,
         particleType=particle_type,
         value=new_data
      )

Intellectual Property Rights Notice | Technical Support