Manage Custom Properties

EDEMpy allows you to read, write, modify, or delete custom properties from a deck. Unlike other EDEMpy writing functionalities, this is not limited to the last Time Step since it is used to write post-processed information back into a completed simulation.

To manage custom properties:

Create a custom property 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 you want defaultValue to have the same value repeated for each dimension, the property’s dimensionality can be expressed as a number as follows:
```
deck.particleCustomProperties.createCustomProperty(
             name="Property Name",
         defaultValue=0.0,
         numElements=3, # This is still a 3D property
```

To read a custom property, the list of existing properties available for each property type as customPropertyNames is available as follows:
```
# Returns a list of the names of all particle custom properties
                deck.particleCustomProperties.customPropertyNames
```
Get the data for a custom property as a Numpy array using the getData() function as follows:
```
deck.particleCustomProperties.getData(
             property="Property Name", # Can alternatively use property ID
             tstep=0, # Timestep index
                particleType=0, # Must specify a particle type
             )
```
Note:
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

To write a custom property, use the setData instead of getData functions, adding a Numpy array (or list) of the desired data as an additional parameter as follows:

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],
                 ]
)

Note: Due to the multi-threaded nature of simulations, the number and ordering of particles will not be the same at each Time Step.

To delete a custom property, use the deleteCustomProperty function as follows:

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

To rename a custom property, use the renameCustomPropertyIndex function as follows:

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

To change the order of custom properties, use the changeCustomPropertyIndex function as follows:

deck.particleCustomProperties.changeCustomPropertyIndex(
               old_index,
               new_index
             )

To get the current index of a property, use the getPropertyIndexForName() function as follows:
```
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
                 )