A P I : S O LV E R MANUAL

Ve r s i o n 2 0 2 2 R 1
 api : solver manual ii
ROCKY

Copyright

copyright ©2022, esss. all rights reserved.

No part of this documentation may be reproduced in any form, by any means,

without the prior written permission of ESSS.

ESSS makes no representations or warranties with respect to the program material

and specifically disclaim any implied warranties, accuracy, merchantability or fitness
for any particular purpose. Furthermore, ESSS reserves the right to revise the
program material and to make changes therein without obligation to notify purchaser
of any revisions or changes except specific errors determined to be incorporated in the
program material. It shall be the responsibility of ESSS to correct any such errors in
an expeditious manner. In no event shall ESSS be liable for any incidental, indirect,
special, or consequential damages arising out of the purchaser’s use of program
material.
Windows and Visual Studio are trademarks of Microsoft Corporation. CUDA is a
trademark of Nvidia Corporation. CentOS is a trademark of Red Hat, Inc. Conda is
copyrighted by Continuum Analytics, Inc.

When referencing this manual in your own article or paper, please

ensure that you use the correct product name, release version, and document
title in your citation.
For example: ESSS Rocky, Release 2022 R1, API : Solver Manual, ESSS Rocky
DEM, S.R.L., (2022).

© 2022, esss - all rights reserved

 api : solver manual iii
ROCKY

Contents

1 Introduction 1

1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 Prerequisites for CentOS 7 Linux . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1.1 Rocky SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1.2 CUDA toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1.3 Build tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2 Prerequisites for Windows 10 . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2.1 Rocky SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2.2 CUDA toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2.3 Build tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Module specification 7

2.1 Structure of the specification file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.2 Module general properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.3 Module material properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.4 Module materials interactions properties . . . . . . . . . . . . . . . . . . . . . . . 13

2.5 Module geometry properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.6 Module particle group properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.7 Module particle input properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.8 Specification of custom models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.9 Specification of variable properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.10 The .plugin file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.11 Module version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.11.1 Migrating between module versions . . . . . . . . . . . . . . . . . . . . . . 25

3 Solver hooks 27

© 2022, esss - all rights reserved

 api : solver manual iv
ROCKY

3.1 Initialization and termination hooks . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.1.1 ROCKY_PLUGIN_CONFIGURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.2 ROCKY_PLUGIN_SETUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.3 ROCKY_PLUGIN_COMPUTE_TIMESTEP . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.4 ROCKY_PLUGIN_COMPUTE_ADHESIVE_DISTANCES . . . . . . . . . . . . . . . . . 29
3.1.5 ROCKY_PLUGIN_INITIALIZE_PARTICLE . . . . . . . . . . . . . . . . . . . . . 29
3.1.6 ROCKY_PLUGIN_INITIALIZE_TRIANGLE . . . . . . . . . . . . . . . . . . . . . 30
3.1.7 ROCKY_PLUGIN_NON_DIMENSIONALIZE . . . . . . . . . . . . . . . . . . . . . . 30
3.1.8 ROCKY_PLUGIN_INITIALIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.1.9 ROCKY_PLUGIN_INITIALIZE_CUDA . . . . . . . . . . . . . . . . . . . . . . . . 31
3.1.10 ROCKY_PLUGIN_TEAR_DOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.1.11 ROCKY_PLUGIN_TEAR_DOWN_CUDA . . . . . . . . . . . . . . . . . . . . . . . . . 32

3.2 General-purpose iteration hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

3.2.1 ROCKY_PLUGIN_BEGIN_ITERATION . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.2 ROCKY_PLUGIN_BEGIN_ITERATION_CUDA . . . . . . . . . . . . . . . . . . . . . 32
3.2.3 ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS . . . . . . . . . . . . . . . . . . . . 33
3.2.4 ROCKY_PLUGIN_PRE_FORCE_ON_PARTICLES . . . . . . . . . . . . . . . . . . . 33
3.2.5 ROCKY_PLUGIN_PRE_FORCE_ON_JOINTS . . . . . . . . . . . . . . . . . . . . . 34
3.2.6 ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS . . . . . . . . . . . . . . . . . . . 34
3.2.7 ROCKY_PLUGIN_POST_FORCE_ON_PARTICLES . . . . . . . . . . . . . . . . . . . 34
3.2.8 ROCKY_PLUGIN_POST_FORCE_ON_JOINTS . . . . . . . . . . . . . . . . . . . . . 35
3.2.9 ROCKY_PLUGIN_PRE_MOVE_PARTICLES . . . . . . . . . . . . . . . . . . . . . . 35
3.2.10 ROCKY_PLUGIN_POST_MOVE_PARTICLES . . . . . . . . . . . . . . . . . . . . . 35

3.3 Hooks associated to specific models . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3.3.1 ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS . . . . . . . . . . . . . . . . . . 36
3.3.2 ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS . . . . . . . . . . . . . . . 36
3.3.3 ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS . . . . . . . . . . . . . . . . . 38
3.3.4 ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS . . . . . . . . . . . . . . 38
3.3.5 ROCKY_PLUGIN_COMPUTE_CONTACT_ADHESIVE_FORCES . . . . . . . . . . . . . 39
3.3.6 ROCKY_PLUGIN_COMPUTE_JOINT_FORCES . . . . . . . . . . . . . . . . . . . . . 39
3.3.7 ROCKY_PLUGIN_COMPUTE_JOINT_BREAKAGE . . . . . . . . . . . . . . . . . . . 40
3.3.8 ROCKY_PLUGIN_INITIALIZE_INSTANTANEOUS_BREAKAGE . . . . . . . . . . . . 40
3.3.9 ROCKY_PLUGIN_COMPUTE_INSTANTANEOUS_BREAKAGE . . . . . . . . . . . . . . 41
3.3.10 ROCKY_PLUGIN_INITIALIZE_FRAGMENTS_SIZE_DISTRIBUTION . . . . . . . . 41
3.3.11 ROCKY_PLUGIN_COMPUTE_FRAGMENTS_SIZE_DISTRIBUTION . . . . . . . . . . 42
3.3.12 ROCKY_PLUGIN_COMPUTE_BOUNDARIES_WEAR . . . . . . . . . . . . . . . . . . . 42
3.3.13 ROCKY_PLUGIN_COMPUTE_CONTACT_HEAT_CONDUCTION . . . . . . . . . . . . . 43
3.3.14 ROCKY_PLUGIN_COMPUTE_THERMAL_INTEGRATION . . . . . . . . . . . . . . . . 43
3.3.15 ROCKY_PLUGIN_COMPUTE_GEOMETRIES_MOTION . . . . . . . . . . . . . . . . . 43

© 2022, esss - all rights reserved

 api : solver manual v
ROCKY

3.4 CFD coupling hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.4.1 ROCKY_PLUGIN_CFD_COUPLING_DRAG_COEFFICIENT . . . . . . . . . . . . . . . 44
3.4.2 ROCKY_PLUGIN_CFD_COUPLING_LIFT_COEFFICIENT . . . . . . . . . . . . . . . 45
3.4.3 ROCKY_PLUGIN_CFD_COUPLING_VIRTUAL_MASS_COEFFICIENT . . . . . . . . . 45
3.4.4 ROCKY_PLUGIN_CFD_COUPLING_TORQUE_COEFFICIENT . . . . . . . . . . . . . 46
3.4.5 ROCKY_PLUGIN_CFD_COUPLING_NUSSELT_NUMBER . . . . . . . . . . . . . . . . 46
3.4.6 ROCKY_PLUGIN_PRE_FORCE_ON_FLUID . . . . . . . . . . . . . . . . . . . . . . 47
3.4.7 ROCKY_PLUGIN_POST_FORCE_ON_FLUID . . . . . . . . . . . . . . . . . . . . . 47
3.4.8 ROCKY_PLUGIN_PRE_MOVE_ON_FLUID . . . . . . . . . . . . . . . . . . . . . . . 47
3.4.9 ROCKY_PLUGIN_POST_MOVE_ON_FLUID . . . . . . . . . . . . . . . . . . . . . . 48

3.5 Output hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.5.1 ROCKY_PLUGIN_PRE_OUTPUT_CUDA_SYNC_DATA . . . . . . . . . . . . . . . . . 48
3.5.2 ROCKY_PLUGIN_PRE_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.5.3 ROCKY_PLUGIN_POST_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4 Miscellaneous topics 50

4.1 CUDA-related macros and specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4.1.1 CUDA_MALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.1.2 CUDA_MALLOC_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.1.3 CUDA_COPY_H2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.1.4 CUDA_COPY_D2H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.1.5 CUDA_MEMSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.1.6 CUDA_FREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.1.7 ROCKY_FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

5 Rocky module examples 53

5.1 A simple custom module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

5.1.1 File spherical_region.plugin . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.1.2 File spherical_region.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.1.3 File spherical_region.pdf . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.1.4 File CMakeLists.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.1.5 File spherical_region.cu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.6 Building procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1.6.1 Building in CentOS 7 . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1.6.2 Building in Windows 10 . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1.7 Running the module in Rocky . . . . . . . . . . . . . . . . . . . . . . . . . 62

5.2 A module implementing a custom model . . . . . . . . . . . . . . . . . . . . . . . 64

5.2.1 Module specification file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.2.2 Implementation of the contact model . . . . . . . . . . . . . . . . . . . . . 67

© 2022, esss - all rights reserved

 api : solver manual vi
ROCKY

5.3 A module implementing variable properties . . . . . . . . . . . . . . . . . . . . . 74

5.3.1 Module specification file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.3.2 Module implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6 Rocky API : Solver classes 82

6.1 IRockyAdhesiveDistanceData class reference . . . . . . . . . . . . . . . . . . . . . 82

6.1.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.1.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.1.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 82
6.1.3.1 set_adhesive_distance() . . . . . . . . . . . . . . . . . . . . . . . . 82

6.2 IRockyInteractionCalculationsData class reference . . . . . . . . . . . . . . . . . . 83

6.2.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.2.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.2.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 83
6.2.3.1 get_geometry_material_index() . . . . . . . . . . . . . . . . . . . 83
6.2.3.2 get_material() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6.2.3.3 get_material_interaction() . . . . . . . . . . . . . . . . . . . . . . . 84
6.2.3.4 get_material_interaction_index() . . . . . . . . . . . . . . . . . . . 84
6.2.3.5 get_number_geometry_materials() . . . . . . . . . . . . . . . . . . 84
6.2.3.6 get_number_particle_groups() . . . . . . . . . . . . . . . . . . . . 84
6.2.3.7 get_particle_material_index() . . . . . . . . . . . . . . . . . . . . . 85
6.2.3.8 get_particle_max_sieve_size() . . . . . . . . . . . . . . . . . . . . . 85
6.2.3.9 get_particle_min_mass() . . . . . . . . . . . . . . . . . . . . . . . . 85
6.2.3.10 get_particle_min_sieve_size() . . . . . . . . . . . . . . . . . . . . . 85

6.3 IRockyPluginData class reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6.3.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.3.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.3.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 86
6.3.3.1 get_geometry_data() . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.3.3.2 get_material_data() . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.3.3.3 get_material_interaction_data() . . . . . . . . . . . . . . . . . . . . 87
6.3.3.4 get_model() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.3.3.5 get_number_geometries() . . . . . . . . . . . . . . . . . . . . . . . 87
6.3.3.6 get_number_material_interactions() . . . . . . . . . . . . . . . . . 87
6.3.3.7 get_number_materials() . . . . . . . . . . . . . . . . . . . . . . . . 87
6.3.3.8 get_number_particle_groups() . . . . . . . . . . . . . . . . . . . . 87
6.3.3.9 get_particle_group_data() . . . . . . . . . . . . . . . . . . . . . . . 88
6.3.3.10 has_geometry_data() . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.3.3.11 has_material_data() . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.3.3.12 has_material_interaction_data() . . . . . . . . . . . . . . . . . . . 88

© 2022, esss - all rights reserved

 api : solver manual vii
ROCKY

6.3.3.13 has_particle_group_data() . . . . . . . . . . . . . . . . . . . . . . . 88

6.4 IRockyPluginDataEntry class reference . . . . . . . . . . . . . . . . . . . . . . . . 88

6.4.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.4.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.4.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 89
6.4.3.1 get_bool() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.4.3.2 get_double() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.4.3.3 get_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.4.3.4 get_list_item() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4.3.5 get_list_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4.3.6 get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4.3.7 has() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

6.5 IRockyTimestepData class reference . . . . . . . . . . . . . . . . . . . . . . . . . . 90

6.5.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.5.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.5.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 91
6.5.3.1 get_loading_n_steps() . . . . . . . . . . . . . . . . . . . . . . . . . 91

6.6 IRockyAdhesionOutputData struct reference . . . . . . . . . . . . . . . . . . . . . 91

6.6.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.6.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.6.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 91
6.6.3.1 set_normal_force() . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.6.3.2 set_tangential_force() . . . . . . . . . . . . . . . . . . . . . . . . . 92

6.7 IRockyBreakableParticle struct reference . . . . . . . . . . . . . . . . . . . . . . . 92

6.7.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.7.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7.3.1 get_breakage_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7.3.2 get_minimum_fragment_size() . . . . . . . . . . . . . . . . . . . . 93
6.7.3.3 get_original_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7.3.4 get_original_volume() . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7.3.5 get_particle_group_index() . . . . . . . . . . . . . . . . . . . . . . 93
6.7.3.6 get_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.7.3.7 get_strength() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.7.3.8 set_as_unbreakable() . . . . . . . . . . . . . . . . . . . . . . . . . . 94

6.8 IRockyContact struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

6.8.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.8.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

© 2022, esss - all rights reserved

 api : solver manual viii
ROCKY

6.8.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 96

6.8.3.1 calculate_relative_velocity() . . . . . . . . . . . . . . . . . . . . . . 96
6.8.3.2 get_contact_position() . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.8.3.3 get_current_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.8.3.4 get_dynamic_friction_coefficient() . . . . . . . . . . . . . . . . . . 97
6.8.3.5 get_equivalent_mass() . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.8.3.6 get_equivalent_radius() . . . . . . . . . . . . . . . . . . . . . . . . 97
6.8.3.7 get_equivalent_stiffness() . . . . . . . . . . . . . . . . . . . . . . . 97
6.8.3.8 get_home_material() . . . . . . . . . . . . . . . . . . . . . . . . . . 98
6.8.3.9 get_home_particle() . . . . . . . . . . . . . . . . . . . . . . . . . . 98
6.8.3.10 get_home_stiffness() . . . . . . . . . . . . . . . . . . . . . . . . . . 98
6.8.3.11 get_is_sliding_marker() . . . . . . . . . . . . . . . . . . . . . . . . 98
6.8.3.12 get_material_interaction() . . . . . . . . . . . . . . . . . . . . . . . 98
6.8.3.13 get_material_interaction_index() . . . . . . . . . . . . . . . . . . . 98
6.8.3.14 get_near_geometry_index() . . . . . . . . . . . . . . . . . . . . . . 99
6.8.3.15 get_near_material() . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.8.3.16 get_near_particle() . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.8.3.17 get_near_stiffness() . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.8.3.18 get_near_triangle() . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.8.3.19 get_normal_adhesion_force() . . . . . . . . . . . . . . . . . . . . . 99
6.8.3.20 get_normal_contact_force() . . . . . . . . . . . . . . . . . . . . . . 100
6.8.3.21 get_normal_relative_velocity() . . . . . . . . . . . . . . . . . . . . 100
6.8.3.22 get_normal_unit_vector() . . . . . . . . . . . . . . . . . . . . . . . 100
6.8.3.23 get_overlap() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
6.8.3.24 get_particle_contact_scalars() . . . . . . . . . . . . . . . . . . . . . 100
6.8.3.25 get_previous_moment_vector() . . . . . . . . . . . . . . . . . . . . 101
6.8.3.26 get_previous_normal_vector() . . . . . . . . . . . . . . . . . . . . 101
6.8.3.27 get_previous_overlap() . . . . . . . . . . . . . . . . . . . . . . . . 101
6.8.3.28 get_reduced_young_modulus() . . . . . . . . . . . . . . . . . . . 101
6.8.3.29 get_restitution_coefficient() . . . . . . . . . . . . . . . . . . . . . . 101
6.8.3.30 get_sliding_distance() . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.8.3.31 get_static_friction_coefficient() . . . . . . . . . . . . . . . . . . . . 102
6.8.3.32 get_tangential_adhesion_force() . . . . . . . . . . . . . . . . . . . 102
6.8.3.33 get_tangential_contact_force() . . . . . . . . . . . . . . . . . . . . 102
6.8.3.34 get_tangential_relative_velocity() . . . . . . . . . . . . . . . . . . 102
6.8.3.35 get_timestep() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
6.8.3.36 get_triangle_contact_scalars() . . . . . . . . . . . . . . . . . . . . . 103
6.8.3.37 is_loading() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
6.8.3.38 is_particle_particle_contact() . . . . . . . . . . . . . . . . . . . . . 103
6.8.3.39 is_particle_triangle_contact() . . . . . . . . . . . . . . . . . . . . . 103
6.8.3.40 is_positive_oriented() . . . . . . . . . . . . . . . . . . . . . . . . . 103

© 2022, esss - all rights reserved

 api : solver manual ix
ROCKY

6.8.3.41 is_unloading() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

6.8.3.42 just_started_adhesive() . . . . . . . . . . . . . . . . . . . . . . . . 104
6.8.3.43 just_started_frictional() . . . . . . . . . . . . . . . . . . . . . . . . 104
6.8.3.44 set_dynamic_friction_coefficient() . . . . . . . . . . . . . . . . . . 104
6.8.3.45 set_previous_moment_vector() . . . . . . . . . . . . . . . . . . . . 104
6.8.3.46 set_restitution_coefficient() . . . . . . . . . . . . . . . . . . . . . . 104
6.8.3.47 set_static_friction_coefficient() . . . . . . . . . . . . . . . . . . . . 105

6.9 IRockyContactIntermediateData struct reference . . . . . . . . . . . . . . . . . . . 105

6.9.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.9.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.9.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 106
6.9.3.1 get_friction_coefficient() . . . . . . . . . . . . . . . . . . . . . . . . 106
6.9.3.2 get_home_centroid_to_contact_point_vector() . . . . . . . . . . . 106
6.9.3.3 get_near_centroid_to_contact_point_vector() . . . . . . . . . . . . 106

6.10 IRockyContactOutputData struct reference . . . . . . . . . . . . . . . . . . . . . . 106

6.10.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.10.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.10.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 107
6.10.3.1 get_normal_force() . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.10.3.2 get_normal_relative_velocity() . . . . . . . . . . . . . . . . . . . . 108
6.10.3.3 get_tangential_force() . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.10.3.4 get_tangential_relative_velocity() . . . . . . . . . . . . . . . . . . 108
6.10.3.5 set_home_impact_energy() . . . . . . . . . . . . . . . . . . . . . . 108
6.10.3.6 set_home_moment() . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.10.3.7 set_near_impact_energy() . . . . . . . . . . . . . . . . . . . . . . . 109
6.10.3.8 set_near_moment() . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.10.3.9 set_normal_force() . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
6.10.3.10 set_rolling_dissipated_power() . . . . . . . . . . . . . . . . . . . . 110
6.10.3.11 set_sliding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
6.10.3.12 set_tangential_force() . . . . . . . . . . . . . . . . . . . . . . . . . 111

6.11 IRockyContactScalars struct reference . . . . . . . . . . . . . . . . . . . . . . . . . 111

6.11.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.11.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.11.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 112
6.11.3.1 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.11.3.2 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.11.3.3 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.11.3.4 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

6.12 IRockyContactScalarsModel struct reference . . . . . . . . . . . . . . . . . . . . . 113

© 2022, esss - all rights reserved

 api : solver manual x
ROCKY

6.12.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

6.12.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.12.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 113
6.12.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6.12.3.2 enable_previous_moment_vector() . . . . . . . . . . . . . . . . . . 114
6.12.3.3 enable_storage_is_sliding_marker() . . . . . . . . . . . . . . . . . 114
6.12.3.4 enable_storage_normal_adhesion_force() . . . . . . . . . . . . . . 115
6.12.3.5 enable_storage_normal_relative_velocity() . . . . . . . . . . . . . 115
6.12.3.6 enable_storage_previous_normal_vector() . . . . . . . . . . . . . 115
6.12.3.7 enable_storage_sliding_distance() . . . . . . . . . . . . . . . . . . 115
6.12.3.8 enable_storage_tangential_adhesion_force() . . . . . . . . . . . . 116
6.12.3.9 enable_storage_tangential_contact_force() . . . . . . . . . . . . . 116
6.12.3.10 enable_storage_tangential_relative_velocity() . . . . . . . . . . . 116
6.12.3.11 enable_variable_dynamic_friction_coefficient() . . . . . . . . . . 117
6.12.3.12 enable_variable_restitution_coefficient() . . . . . . . . . . . . . . 117
6.12.3.13 enable_variable_static_friction_coefficient() . . . . . . . . . . . . . 117
6.12.3.14 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
6.12.3.15 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
6.12.3.16 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

6.13 IRockyCurveCollectionData struct reference . . . . . . . . . . . . . . . . . . . . . 118

6.13.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
6.13.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
6.13.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 119
6.13.3.1 add_curve() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
6.13.3.2 create_dataset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
6.13.3.3 create_geometry_curve() . . . . . . . . . . . . . . . . . . . . . . . 120
6.13.3.4 create_geometry_dataset() . . . . . . . . . . . . . . . . . . . . . . 120
6.13.3.5 create_geometry_time_curve() . . . . . . . . . . . . . . . . . . . . 121
6.13.3.6 create_particles_curve() . . . . . . . . . . . . . . . . . . . . . . . . 121
6.13.3.7 create_particles_dataset() . . . . . . . . . . . . . . . . . . . . . . . 121
6.13.3.8 create_particles_time_curve() . . . . . . . . . . . . . . . . . . . . . 121
6.13.3.9 create_time_curve() . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.13.3.10 setup_dataset_dimension() . . . . . . . . . . . . . . . . . . . . . . 122
6.13.3.11 setup_geometry_dataset_dimension() . . . . . . . . . . . . . . . . 122
6.13.3.12 setup_geometry_time_curve_dimension() . . . . . . . . . . . . . 123
6.13.3.13 setup_particles_dataset_dimension() . . . . . . . . . . . . . . . . 123
6.13.3.14 setup_particles_time_curve_dimension() . . . . . . . . . . . . . . 123
6.13.3.15 setup_time_curve_dimension() . . . . . . . . . . . . . . . . . . . . 124
6.13.3.16 update_dataset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
6.13.3.17 update_geometry_dataset() . . . . . . . . . . . . . . . . . . . . . . 124

© 2022, esss - all rights reserved

 api : solver manual xi
ROCKY

6.13.3.18 update_geometry_time_curve() . . . . . . . . . . . . . . . . . . . 125

6.13.3.19 update_particles_dataset() . . . . . . . . . . . . . . . . . . . . . . 125
6.13.3.20 update_particles_time_curve() . . . . . . . . . . . . . . . . . . . . 125
6.13.3.21 update_time_curve() . . . . . . . . . . . . . . . . . . . . . . . . . . 126

6.14 IRockyCFDProperties struct reference . . . . . . . . . . . . . . . . . . . . . . . . . 126

6.14.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6.14.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6.14.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 127
6.14.3.1 compute_fluid_vorticity() . . . . . . . . . . . . . . . . . . . . . . . 127
6.14.3.2 compute_relative_angular_reynolds_number() . . . . . . . . . . . 127
6.14.3.3 compute_vorticity_reynolds_number() . . . . . . . . . . . . . . . 127
6.14.3.4 get_cell_volume() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.14.3.5 get_cfd_time_step() . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.14.3.6 get_fluid_density() . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.14.3.7 get_fluid_pressure_gradient() . . . . . . . . . . . . . . . . . . . . 128
6.14.3.8 get_fluid_specific_heat() . . . . . . . . . . . . . . . . . . . . . . . . 128
6.14.3.9 get_fluid_temperature() . . . . . . . . . . . . . . . . . . . . . . . . 128
6.14.3.10 get_fluid_thermal_conductivity() . . . . . . . . . . . . . . . . . . 128
6.14.3.11 get_fluid_viscosity() . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.14.3.12 get_prandtl_number() . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.14.3.13 get_relative_velocity() . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.14.3.14 get_reynolds_number() . . . . . . . . . . . . . . . . . . . . . . . . 129
6.14.3.15 get_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.14.3.16 get_solid_fraction() . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

6.15 IRockyDeviceModel struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . 129

6.15.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.15.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.15.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 130
6.15.3.1 get_current_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.15.3.2 get_particle_cloud_point() . . . . . . . . . . . . . . . . . . . . . . 130
6.15.3.3 get_time_step() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

6.16 IRockyFluidScalars struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

6.16.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.16.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.16.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 131
6.16.3.1 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.16.3.2 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.16.3.3 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.16.3.4 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

© 2022, esss - all rights reserved

 api : solver manual xii
ROCKY

6.17 IRockyFluidScalarsModel struct reference . . . . . . . . . . . . . . . . . . . . . . . 132

6.17.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.17.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.17.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 133
6.17.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.17.3.2 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.17.3.3 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.17.3.4 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

6.18 IRockyGeometriesMotionData struct reference . . . . . . . . . . . . . . . . . . . . 134

6.18.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.18.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.18.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 134
6.18.3.1 get_geometry() [1/2] . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.18.3.2 get_geometry() [2/2] . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.18.3.3 get_number_of_geometries() . . . . . . . . . . . . . . . . . . . . . 135

6.19 IRockyGeometryMotionData struct reference . . . . . . . . . . . . . . . . . . . . . 135

6.19.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.19.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.19.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 136
6.19.3.1 get_force() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.19.3.2 get_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.19.3.3 get_moment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.19.3.4 get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.19.3.5 get_orientation_euler_angles() . . . . . . . . . . . . . . . . . . . . 137
6.19.3.6 get_orientation_quaternion() . . . . . . . . . . . . . . . . . . . . . 137
6.19.3.7 get_position() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.19.3.8 get_rotational_velocity() . . . . . . . . . . . . . . . . . . . . . . . . 137
6.19.3.9 get_translational_velocity() . . . . . . . . . . . . . . . . . . . . . . 137
6.19.3.10 set_orientation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.19.3.11 set_orientation_angles() . . . . . . . . . . . . . . . . . . . . . . . . 138
6.19.3.12 set_position() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.19.3.13 set_rotational_velocity() . . . . . . . . . . . . . . . . . . . . . . . . 138
6.19.3.14 set_translational_velocity() . . . . . . . . . . . . . . . . . . . . . . 138

6.20 IRockyGeometryTriangle struct reference . . . . . . . . . . . . . . . . . . . . . . . 139

6.20.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.20.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.20.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 140
6.20.3.1 get_area() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.20.3.2 get_centroid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

© 2022, esss - all rights reserved

 api : solver manual xiii
ROCKY

6.20.3.3 get_geometry_index() . . . . . . . . . . . . . . . . . . . . . . . . . 140

6.20.3.4 get_geometry_rotation_center() . . . . . . . . . . . . . . . . . . . 140
6.20.3.5 get_geometry_rotational_velocity() . . . . . . . . . . . . . . . . . 140
6.20.3.6 get_material() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.20.3.7 get_material_index() . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.20.3.8 get_normal_unit_vector() . . . . . . . . . . . . . . . . . . . . . . . 141
6.20.3.9 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.20.3.10 get_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.20.3.11 get_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.20.3.12 get_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 141
6.20.3.13 get_translational_velocity() . . . . . . . . . . . . . . . . . . . . . . 141
6.20.3.14 is_adiabatic() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.20.3.15 set_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.20.3.16 set_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.20.3.17 set_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 142

6.21 IRockyGeometryTriangleHost struct reference . . . . . . . . . . . . . . . . . . . . 143

6.21.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.21.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.21.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 143
6.21.3.1 get_area() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.21.3.2 get_centroid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.21.3.3 get_geometry_index() . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.21.3.4 get_geometry_rotation_center() . . . . . . . . . . . . . . . . . . . 144
6.21.3.5 get_geometry_rotational_velocity() . . . . . . . . . . . . . . . . . 144
6.21.3.6 get_material() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.21.3.7 get_material_index() . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.21.3.8 get_normal_unit_vector() . . . . . . . . . . . . . . . . . . . . . . . 144
6.21.3.9 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.21.3.10 get_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
6.21.3.11 get_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
6.21.3.12 get_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 145
6.21.3.13 get_translational_velocity() . . . . . . . . . . . . . . . . . . . . . . 145
6.21.3.14 is_adiabatic() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.21.3.15 set_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.21.3.16 set_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.21.3.17 set_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 146

6.22 IRockyJoint struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

6.22.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
6.22.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.22.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 148

© 2022, esss - all rights reserved

 api : solver manual xiv
ROCKY

6.22.3.1 get_angle_scaling_factor() . . . . . . . . . . . . . . . . . . . . . . . 148

6.22.3.2 get_angular_damping_coefficient() . . . . . . . . . . . . . . . . . 148
6.22.3.3 get_angular_deformation() . . . . . . . . . . . . . . . . . . . . . . 149
6.22.3.4 get_angular_deformation_direction() . . . . . . . . . . . . . . . . 149
6.22.3.5 get_angular_deformation_velocity() . . . . . . . . . . . . . . . . . 149
6.22.3.6 get_angular_stiffness() . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.22.3.7 get_area() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.22.3.8 get_area_moment_of_inertia() . . . . . . . . . . . . . . . . . . . . 150
6.22.3.9 get_bending_elastic_ratio() . . . . . . . . . . . . . . . . . . . . . . 151
6.22.3.10 get_damping_force() . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.22.3.11 get_damping_moment() . . . . . . . . . . . . . . . . . . . . . . . . 151
6.22.3.12 get_elastic_force() . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.22.3.13 get_elastic_moment() . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.22.3.14 get_home_arm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.22.3.15 get_home_element_centroid_position() . . . . . . . . . . . . . . . 152
6.22.3.16 get_home_element_orientation() . . . . . . . . . . . . . . . . . . . 152
6.22.3.17 get_moments_due_to_force() . . . . . . . . . . . . . . . . . . . . . 153
6.22.3.18 get_near_arm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.22.3.19 get_near_element_centroid_position() . . . . . . . . . . . . . . . . 153
6.22.3.20 get_near_element_orientation() . . . . . . . . . . . . . . . . . . . . 153
6.22.3.21 get_normal_damping_coefficient() . . . . . . . . . . . . . . . . . . 154
6.22.3.22 get_normal_deformation() . . . . . . . . . . . . . . . . . . . . . . 154
6.22.3.23 get_normal_deformation_velocity() . . . . . . . . . . . . . . . . . 154
6.22.3.24 get_normal_elastic_ratio() . . . . . . . . . . . . . . . . . . . . . . . 154
6.22.3.25 get_normal_stiffness() . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.22.3.26 get_normal_vector() . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.22.3.27 get_number_angular_deformations() . . . . . . . . . . . . . . . . 155
6.22.3.28 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.22.3.29 get_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.22.3.30 get_tangential_damping_coefficient() . . . . . . . . . . . . . . . . 156
6.22.3.31 get_tangential_deformation() . . . . . . . . . . . . . . . . . . . . . 156
6.22.3.32 get_tangential_deformation_velocity() . . . . . . . . . . . . . . . 156
6.22.3.33 get_tangential_elastic_ratio() . . . . . . . . . . . . . . . . . . . . . 156
6.22.3.34 get_tangential_stiffness() . . . . . . . . . . . . . . . . . . . . . . . 157
6.22.3.35 get_torsion_elastic_ratio() . . . . . . . . . . . . . . . . . . . . . . . 157
6.22.3.36 get_young_modulus() . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.22.3.37 get_young_modulus_multiplier() . . . . . . . . . . . . . . . . . . 157

6.23 IRockyJointScalars struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

6.23.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.23.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

© 2022, esss - all rights reserved

 api : solver manual xv
ROCKY

6.23.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 158

6.23.3.1 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.23.3.2 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.23.3.3 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.23.3.4 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

6.24 IRockyJointScalarsModel struct reference . . . . . . . . . . . . . . . . . . . . . . . 159

6.24.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.24.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.24.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 159
6.24.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.24.3.2 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.24.3.3 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.24.3.4 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

6.25 IRockyMaterial struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

6.25.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.25.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.25.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 161
6.25.3.1 get_density() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.25.3.2 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.25.3.3 get_specific_heat() . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.25.3.4 get_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 162
6.25.3.5 get_young_modulus() . . . . . . . . . . . . . . . . . . . . . . . . . 162

6.26 IRockyMaterialInteraction struct reference . . . . . . . . . . . . . . . . . . . . . . 162

6.26.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.26.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.26.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 163
6.26.3.1 get_dynamic_friction_coefficient() . . . . . . . . . . . . . . . . . . 163
6.26.3.2 get_minimum_restitution_coefficient() . . . . . . . . . . . . . . . 163
6.26.3.3 get_restitution_coefficient() . . . . . . . . . . . . . . . . . . . . . . 163
6.26.3.4 get_static_friction_coefficient() . . . . . . . . . . . . . . . . . . . . 163
6.26.3.5 get_stiffness_multiplier() . . . . . . . . . . . . . . . . . . . . . . . 163
6.26.3.6 get_tangential_stiffness_ratio() . . . . . . . . . . . . . . . . . . . . 164

6.27 IRockyModel struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

6.27.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
6.27.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.27.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 165
6.27.3.1 find_point_cloud() . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.27.3.2 find_point_cloud_property() . . . . . . . . . . . . . . . . . . . . . 165
6.27.3.3 get_coupling_mode() . . . . . . . . . . . . . . . . . . . . . . . . . 166

© 2022, esss - all rights reserved

 api : solver manual xvi
ROCKY

6.27.3.4 get_current_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

6.27.3.5 get_curve_collections() . . . . . . . . . . . . . . . . . . . . . . . . 166
6.27.3.6 get_device_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
6.27.3.7 get_energy_factor() . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
6.27.3.8 get_fluid_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
6.27.3.9 get_force_factor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.27.3.10 get_geometry_name() . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.27.3.11 get_interactions_data() . . . . . . . . . . . . . . . . . . . . . . . . 167
6.27.3.12 get_joint_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.27.3.13 get_length_factor() . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.27.3.14 get_mass_factor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.27.3.15 get_number_of_active_particles() . . . . . . . . . . . . . . . . . . 168
6.27.3.16 get_number_of_active_triangles() . . . . . . . . . . . . . . . . . . 168
6.27.3.17 get_number_of_devices() . . . . . . . . . . . . . . . . . . . . . . . 168
6.27.3.18 get_number_of_geometries() . . . . . . . . . . . . . . . . . . . . . 168
6.27.3.19 get_number_of_material_interactions() . . . . . . . . . . . . . . . 168
6.27.3.20 get_number_of_materials() . . . . . . . . . . . . . . . . . . . . . . 168
6.27.3.21 get_number_of_particle_groups() . . . . . . . . . . . . . . . . . . 168
6.27.3.22 get_number_of_particles() . . . . . . . . . . . . . . . . . . . . . . 169
6.27.3.23 get_number_of_processes() . . . . . . . . . . . . . . . . . . . . . . 169
6.27.3.24 get_output_interval() . . . . . . . . . . . . . . . . . . . . . . . . . 169
6.27.3.25 get_particle_breakage_scalars() . . . . . . . . . . . . . . . . . . . . 169
6.27.3.26 get_particle_contact_scalars() . . . . . . . . . . . . . . . . . . . . . 169
6.27.3.27 get_particle_group_name() . . . . . . . . . . . . . . . . . . . . . . 169
6.27.3.28 get_particle_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . 170
6.27.3.29 get_particle_transfer_scalars() . . . . . . . . . . . . . . . . . . . . 170
6.27.3.30 get_pressure_factor() . . . . . . . . . . . . . . . . . . . . . . . . . . 170
6.27.3.31 get_softening_factor() . . . . . . . . . . . . . . . . . . . . . . . . . 170
6.27.3.32 get_temperature_factor() . . . . . . . . . . . . . . . . . . . . . . . 170
6.27.3.33 get_time_factor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
6.27.3.34 get_triangle_contact_scalars() . . . . . . . . . . . . . . . . . . . . . 171
6.27.3.35 get_triangle_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . 171
6.27.3.36 is_thermal_simulation() . . . . . . . . . . . . . . . . . . . . . . . . 171
6.27.3.37 set_adhesive_distance() . . . . . . . . . . . . . . . . . . . . . . . . 171
6.27.3.38 set_minimum_restitution_coefficient() . . . . . . . . . . . . . . . 171
6.27.3.39 set_point_cloud_property_dimension() . . . . . . . . . . . . . . . 172

6.28 IRockyParticle struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

6.28.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
6.28.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
6.28.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 174

© 2022, esss - all rights reserved

 api : solver manual xvii
ROCKY

6.28.3.1 add_force() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

6.28.3.2 add_moment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
6.28.3.3 disable_related_particle_contacts() . . . . . . . . . . . . . . . . . . 174
6.28.3.4 disable_related_triangle_contacts() . . . . . . . . . . . . . . . . . 174
6.28.3.5 enable_related_particle_contacts() . . . . . . . . . . . . . . . . . . 174
6.28.3.6 enable_related_triangle_contacts() . . . . . . . . . . . . . . . . . . 174
6.28.3.7 get_breakage_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . 175
6.28.3.8 get_centroid_position() . . . . . . . . . . . . . . . . . . . . . . . . 175
6.28.3.9 get_cgm_scale_factor() . . . . . . . . . . . . . . . . . . . . . . . . . 175
6.28.3.10 get_equivalent_diameter() . . . . . . . . . . . . . . . . . . . . . . . 175
6.28.3.11 get_gravity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
6.28.3.12 get_impact_energy() . . . . . . . . . . . . . . . . . . . . . . . . . . 175
6.28.3.13 get_mass() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
6.28.3.14 get_material() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
6.28.3.15 get_material_index() . . . . . . . . . . . . . . . . . . . . . . . . . . 176
6.28.3.16 get_orientation_axis_angle() . . . . . . . . . . . . . . . . . . . . . 176
6.28.3.17 get_orientation_quaternion() . . . . . . . . . . . . . . . . . . . . . 176
6.28.3.18 get_original_mass() . . . . . . . . . . . . . . . . . . . . . . . . . . 176
6.28.3.19 get_particle_group_index() . . . . . . . . . . . . . . . . . . . . . . 177
6.28.3.20 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
6.28.3.21 get_release_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
6.28.3.22 get_rolling_resistance_coefficient() . . . . . . . . . . . . . . . . . . 177
6.28.3.23 get_rotational_velocity() . . . . . . . . . . . . . . . . . . . . . . . . 177
6.28.3.24 get_scalars() [1/2] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
6.28.3.25 get_scalars() [2/2] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
6.28.3.26 get_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
6.28.3.27 get_specific_heat() . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
6.28.3.28 get_sphericity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
6.28.3.29 get_strength() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
6.28.3.30 get_surface_area() . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
6.28.3.31 get_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 178
6.28.3.32 get_transfer_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.28.3.33 get_translational_velocity() . . . . . . . . . . . . . . . . . . . . . . 179
6.28.3.34 get_volume() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.28.3.35 remove() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.28.3.36 set_frozen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.28.3.37 set_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.28.3.38 set_specific_heat() . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
6.28.3.39 set_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 180

6.29 IRockyParticleBreakageScalars struct reference . . . . . . . . . . . . . . . . . . . . 180

© 2022, esss - all rights reserved

 api : solver manual xviii
ROCKY

6.29.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

6.29.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
6.29.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 181
6.29.3.1 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.29.3.2 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.29.3.3 get_t10() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.29.3.4 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.29.3.5 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.29.3.6 set_t10() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

6.30 IRockyParticleBreakageScalarsModel struct reference . . . . . . . . . . . . . . . . 182

6.30.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.30.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.30.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 183
6.30.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
6.30.3.2 enable_t10() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
6.30.3.3 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
6.30.3.4 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
6.30.3.5 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

6.31 IRockyParticleCloudPoint struct reference . . . . . . . . . . . . . . . . . . . . . . . 184

6.31.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
6.31.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
6.31.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 185
6.31.3.1 get_position() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
6.31.3.2 get_property() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

6.32 IRockyParticleHost struct reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

6.32.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
6.32.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3.1 get_centroid_position() . . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3.2 get_cgm_scale_factor() . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3.3 get_equivalent_diameter() . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3.4 get_material() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3.5 get_material_index() . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.32.3.6 get_original_mass() . . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.32.3.7 get_original_volume() . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.32.3.8 get_release_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.32.3.9 get_scalars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.32.3.10 get_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.32.3.11 is_released() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

© 2022, esss - all rights reserved

 api : solver manual xix
ROCKY

6.33 IRockyParticleScalars struct reference . . . . . . . . . . . . . . . . . . . . . . . . . 187

6.33.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
6.33.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
6.33.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 188
6.33.3.1 add_explicit_fluid_heat_transfer_rate() . . . . . . . . . . . . . . . 188
6.33.3.2 add_explicit_fluid_momentum() . . . . . . . . . . . . . . . . . . . 189
6.33.3.3 add_implicit_fluid_heat_transfer_rate() . . . . . . . . . . . . . . . 189
6.33.3.4 add_implicit_fluid_momentum() . . . . . . . . . . . . . . . . . . . 189
6.33.3.5 add_mass_increment() . . . . . . . . . . . . . . . . . . . . . . . . . 190
6.33.3.6 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
6.33.3.7 add_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
6.33.3.8 add_volume_increment() . . . . . . . . . . . . . . . . . . . . . . . 190
6.33.3.9 get_mass_increment() . . . . . . . . . . . . . . . . . . . . . . . . . 190
6.33.3.10 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.33.3.11 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.33.3.12 get_specific_heat() . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.33.3.13 get_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.33.3.14 get_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 191
6.33.3.15 get_volume_increment() . . . . . . . . . . . . . . . . . . . . . . . . 192
6.33.3.16 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
6.33.3.17 set_mass_increment() . . . . . . . . . . . . . . . . . . . . . . . . . 192
6.33.3.18 set_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
6.33.3.19 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.33.3.20 set_specific_heat() . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.33.3.21 set_temperature() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.33.3.22 set_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 193
6.33.3.23 set_volume_increment() . . . . . . . . . . . . . . . . . . . . . . . . 193

6.34 IRockyParticleScalarsModel struct reference . . . . . . . . . . . . . . . . . . . . . 194

6.34.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.34.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.34.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 194
6.34.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.34.3.2 enable_mass_increment() . . . . . . . . . . . . . . . . . . . . . . . 195
6.34.3.3 enable_variable_poisson_ratio() . . . . . . . . . . . . . . . . . . . 195
6.34.3.4 enable_variable_specific_heat() . . . . . . . . . . . . . . . . . . . . 195
6.34.3.5 enable_variable_thermal_conductivity() . . . . . . . . . . . . . . 195
6.34.3.6 enable_volume_increment() . . . . . . . . . . . . . . . . . . . . . . 196
6.34.3.7 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
6.34.3.8 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
6.34.3.9 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

© 2022, esss - all rights reserved

 api : solver manual xx
ROCKY

6.35 IRockyParticleTransferScalars struct reference . . . . . . . . . . . . . . . . . . . . 197

6.35.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.35.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.35.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 197
6.35.3.1 add_heat_source() . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.35.3.2 add_heat_transfer() . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.35.3.3 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.35.3.4 get_heat_transfer() . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.35.3.5 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.35.3.6 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.35.3.7 set_heat_transfer() . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
6.35.3.8 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

6.36 IRockyParticleTransferScalarsModel struct reference . . . . . . . . . . . . . . . . 199

6.36.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
6.36.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
6.36.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 200
6.36.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
6.36.3.2 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
6.36.3.3 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
6.36.3.4 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

6.37 IRockyTriangleScalars struct reference . . . . . . . . . . . . . . . . . . . . . . . . . 201

6.37.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
6.37.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
6.37.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 202
6.37.3.1 add_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
6.37.3.2 get_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
6.37.3.3 get_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
6.37.3.4 get_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 202
6.37.3.5 max_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
6.37.3.6 set_poisson_ratio() . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
6.37.3.7 set_scalar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
6.37.3.8 set_thermal_conductivity() . . . . . . . . . . . . . . . . . . . . . . 203

6.38 IRockyTriangleScalarsModel struct reference . . . . . . . . . . . . . . . . . . . . . 204

6.38.1 Public member functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
6.38.2 Detailed description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
6.38.3 Member function documentation . . . . . . . . . . . . . . . . . . . . . . . . 204
6.38.3.1 add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
6.38.3.2 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
6.38.3.3 reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

© 2022, esss - all rights reserved

 api : solver manual xxi
ROCKY

6.38.3.4 set_dimension() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

© 2022, esss - all rights reserved

 api : solver manual 1
ROCKY

1 Introduction
The Rocky SDK enables the development of custom modules for
Rocky. A Rocky module is a compiled library that attaches to the
Rocky solver at strategic points during the simulation, allowing
execution of custom code. For example, Rocky modules empower
users to:

• Apply custom models to some simulated entities.

• Collect custom statistics during the simulation.

• Create custom post-processing data.

The Rocky SDK comprises:

• Runtime libraries for binding to Rocky simulations at

strategic moments.

• C++ header files that export types and macros related

to the simulation state.

• Mechanisms to ease compilation of Rocky modules.

1.1 Prerequisites
The Rocky SDK is supported for the following operating systems:

• CentOS 7 Linux 64-bit

• Windows 10 64-bit

This manual assumes that your system is one of the above and
Rocky can perform a simulation successfully in this system.1 1
Refer to the Rocky User Manual or
search the Rocky support channels if
The Rocky SDK package for both supported operating sys- you’re unable to run Rocky.
tems can be downloaded from https://support.esss.co/hc/en-us/
articles/360049311911
It is assumed that users of the Rocky SDK have basic knowledge
of the C++ and Python programming languages.

© 2022, esss - all rights reserved

 api : solver manual 2
ROCKY

1.1.1 Prerequisites for CentOS 7 Linux

1.1.1.1 Rocky SDK

Unzip the Rocky SDK for Linux in a folder of your choice. Set the
environment variable RockySDK_DIR with the location of the unzipped
sdk subdirectory.
The version of the Rocky SDK is identified in the name of its zip
file. It is paramount that you install a Rocky SDK of the same version
as the Rocky application upon which your module is designed to
run.2 2
The version of Rocky can be discov-
ered by choosing Help → About in the
application menus.

1.1.1.2 CUDA toolkit

Install the CUDA toolkit 11.6.0 for Linux x86_64, CentOS 7 from
https://developer.nvidia.com/cuda-11-6-0-download-archive. Set
the environment variable CUDA_PATH_V11_1 with the location of the
installed CUDA toolkit.3 3
Typically:
CUDA_PATH_V11_6=/usr/local/cuda-11.6/

1.1.1.3 Build tools

Install Miniconda for Python 3.8 Linux 64-bit from https://docs.

conda.io/en/latest/miniconda.html. Activate a conda prompt and
install the following packages:

• make
• cmake
• "gxx_linux-64>=7,<8"

The conda prompt now contains a minimum set of tools required to

build Rocky modules.

1.1.2 Prerequisites for Windows 10

1.1.2.1 Rocky SDK

Unzip the Rocky SDK for Windows in a folder of your choice. Set the
environment variable RockySDK_DIR with the location of the unzipped
sdk subdirectory.
The version of the Rocky SDK is identified in the name of its zip
file. It is paramount that you install a Rocky SDK of the same version
as the Rocky application upon which your module is designed to
4
The version of Rocky can be discov-
ered by choosing Help → About in the
run.4 application menus.

© 2022, esss - all rights reserved

 api : solver manual 3
ROCKY

1.1.2.2 CUDA toolkit

Install the CUDA toolkit 11.6.0 for Windows 10 from https://

developer.nvidia.com/cuda-11-6-0-download-archive. Set the
environment variable CUDA_PATH_V11_1 with the location of the
CUDA toolkit.5 5
Typically C:\Program Files\NVIDIA
GPU Computing Toolkit\CUDA\v11.6.

1.1.2.3 Build tools

Install Visual Studio Build Tools 2019, version 16.8.4, from:

https://download.visualstudio.microsoft.com/
download/pr/bacf7555-1a20-4bf4-ae4d-1003bbc25da8/
f3a7e2868c203490a4095231e20e628bf661b7469f2d53626f3fbbdfc161d471/
vs_BuildTools.exe

Be sure to install the Desktop development with C++ workload

with at least the following components:

• VC++ 2019 version latest tools

• Windows 10 SDK
• Visual C++ tools for CMake

1.2 Glossary
The glossary below includes the definition of the main terms and
concepts used in the description of the Rocky API : Solver in the
remainder of this manual.

Adhesive contact A contact in which the interaction force is adhesive. There is no

need of physical contact for an adhesive force to exist between two
entities (two particles or a particle and a boundary triangle). In
Rocky, an adhesive contact will exist if an adhesive model is active
and the gap between the two entities is smaller than the adhesive
distance.

Adhesive distance A value defined per material interaction, that specifies the limiting
distance (gap) for an adhesion contact to exist between two entities
associated to that material interaction.

Boundary A boundary or geometry is each one of the individual surfaces,

formed by boundary triangles, that interacts with the particles

© 2022, esss - all rights reserved

 api : solver manual 4
ROCKY

during a simulation. A custom module can define custom geometry

properties whose values can be specified in runtime through the
Rocky UI for each boundary in a project.

Boundary triangle Each one of the triangles that make up a geometry or boundary.

CUDA Acronym for Compute Unified Device Architecture, which is a

parallel computing platform that allows developers to use a CUDA-
enabled GPU for general purpose processing. It is the platform used
by Rocky to process simulations in GPU.

Contact Computational representation of any pair particle/particle or

particle/boundary-triangle that has a force interaction at a given
time in a simulation. Rocky is constantly updating the list of active
contacts, according to the instantaneous positions of the particles in
a simulation.

Contact model The sequence of calculations made by a contact model, where the
pipeline output of one calculation is passed as an input to the next one. It
can be customized through the implementation of a custom contact
model on an external module.

Device In CUDA-related operations, it refers to the GPU and its memory.

Discrete breakage Breakage modeling applicable only to flexible particles (fibers, shells,
and solid) in which the bonding action of a joint is disabled when
the breakage criterion is satisfied.

Element Each one of the pieces that make up a flexible particle. In Rocky,
elements are sphero-cylinders in a flexible fiber, sphero-triangles in
a flexible shell, and tetrahedra in a solid flexible particle.

Frictional contact A contact in which the two entities are physically touching each
other. That is, there is an actual overlap between the entities and,
therefore, a contact force acting on both of them.

Home entity In contexts where a pair of entities is involved, one of these entities
is always labeled as home. In contacts, it is always a particle,
independent of the contact type. In joints, it is always an individual
element making up the particle. There is no special rule for labeling
an entity as home when the two entities have the same type.

© 2022, esss - all rights reserved

 api : solver manual 5
ROCKY

Hook Location within the Rocky solver at which the Rocky API : Solver
allows modules to insert custom C++ code in order to implement
new functionalities or modify some specific behavior.

Host In CUDA-related operations, it refers to the CPU and its memory.

Instantaneous Breakage modeling applicable only to non-flexible polyhedral

breakage particles in which all the resulting fragments are generated at the
same time when the breakage criterion is satisfied.

Joint A joint is the entity that links two elements in a multi-element

flexible particle. A joint applies forces and moments over the joined
elements as a reaction to translational and angular deformations,
respectively. A joint model specifies how those forces and moments
are related to those deformations.

Known scalar A type of scalar variable that is defined within the Rocky solver, but
can be accessed from a custom module, if necessary.

Material An abstraction of the material that makes up particles or boundaries

in Rocky. A material has associated values of physical properties
that are common to all particles in a particle group or to a whole
boundary.

Material interaction Any of the combinations of two materials defined in a project. A

material interaction is a computational abstraction that associates
common properties to all contacts in which each one of the two
contacting entities is made of one of the two materials considered
in the material interaction. A custom module can define custom
material interaction properties whose values can be specified in
runtime through the Rocky UI for each material interaction in a
project.

Module A component which is external to the Rocky core solver and that
implements a specific feature or overrides a built-in model. The
main purpose of the Rocky SDK is to enable users to implement
custom modules.

Multi-element A flexible particle formed by more than one element. Rocky supports
particle three types of multi-element particles: fibers, shells and solid
particles.

Near entity In contexts where a pair of entities is involved, one of these entities
is always labeled as near. In contacts, it is always the entity (particle

© 2022, esss - all rights reserved

 api : solver manual 6
ROCKY

or triangle) in contact with the home particle. In joints, it is always

the individual element that is linked to the home element by a joint.

Particle group A collection of particles with the same shape, material, and other
defining characteristics, such as size distribution, flexibility, breakage
capabilities, etc.

Point cloud A set of points without a connectivity structure, located inside the
solution domain. The spatial distribution of one or more physical
quantities can be defined by assigning values to each point belonging
to a point cloud. Those values can be retrieved during the execution
of a simulation though special API methods, in order to be used in
custom models.

Scalar A special type of variable associated to a specific type of entity

in Rocky (particles, boundary triangles, joints, or contacts) that is
designed to store values that persist throughout a simulation.

Transfer scalar A type of scalar variable whose values are reset automatically at the
beginning of each new time iteration. Currently defined only for
particles, it is typically used to sum values coming from different
contacts associated to a particle at a given time.

© 2022, esss - all rights reserved

 api : solver manual 7
ROCKY

2 Module specification
The way that a custom module must interact with the Rocky UI is
specified by means of a Python file. From this file, Rocky extracts two
primary kinds of information:

• The definition of the custom parameters that must be

displayed at specific places within the Rocky UI.

• Whether or not the module implements a custom

model that will override a built-in model or will be
added to the existing built-in models in Rocky.

The way in which these specifications must be coded is described

throughout this chapter. It is assumed that users have a basic
knowledge of the Python language.

2.1 Structure of the specification file

The first operation that must be made in the file is the importation
of some utilities, most of them defined by the Rocky SDK itself. The
following block includes the most commonly needed utilities:

from pathlib import Path

from rocky20.addins.addin_models import data_model, container_model
from rocky20.addins.addin_specs import RockyAddinSpecs
from rocky20.addins.addin_types import (Boolean, Quantity, String, List,
ScalarProperties)
from yapsy.IPlugin import IPlugin

The most important class that must be defined in the file is the one
derived from the IPlugin class because it implements the method
get_addin_specs. It is through the get_addin_specs method that
Rocky will receive in runtime all the specifications for the module.

© 2022, esss - all rights reserved

 api : solver manual 8
ROCKY

class CustomModule(IPlugin):
def get_addin_specs(self):
return CustomModuleSpecs

In the example above, CustomModuleSpecs is a class that will

contain all the specifications for the module. Its implementation
can follow this general example:

class CustomModuleSpecs(RockyAddinSpecs):

name = NAME

model = CustomGeneralParameters

instantaneous_breakage_model = CustomModel

material_properties = CustomMaterialProperties

material_interaction_properties = CustomInteractionProperties

geometry_properties = CustomGeometryProperties

particle_group_properties = CustomParticleGroupProperties

particle_input_properties = CustomParticleInputProperties

def CreateAddin(cls):
return cls.CreateDynamicAddin(Path(__file__).parent, ’custom_module_name’)

The only items whose inclusion is mandatory in this code block are
the definition of the variables name and model, besides the definition
of the method CreateAddin. The meaning of each one of the members
in this class is described as follows:

• name is the string label that will identify the module in

the Rocky UI.

• model is the set of specifications for the module’s gen-

eral parameters. These parameters are not associated
to specific entities of the Rocky UI.

• instantaneous_breakage_model is an example specifi-

cation of a new custom model for an existing category

© 2022, esss - all rights reserved

 api : solver manual 9
ROCKY

of models in Rocky. In this case, the module is

indicating that it implements a custom model for
instantaneous breakage. All customizable models in
the current version of Rocky are listed in Table 2.1.

• material_properties is the set of specifications of the

module’s parameters that Rocky must associate to
materials.

• material_interaction_properties is the set of speci-

fications of the module’s parameters that Rocky must
associate to materials interactions.

• geometry_properties is the set of specifications of the

module’s parameters that Rocky must associate to
boundaries (geometries).

• particle_group_properties is the set of specifications

of the module’s parameters that Rocky must associate
to particle groups.

• particle_input_properties is the set of specifications

of particle scalar variables that need an initial value
when particles enter into the solution domain.

• CreateAddin is a method that handles the loading of

the compiled library file for the module when the
simulation starts.

For the specification of a module to be complete, each one of the

green variables in the block above must be properly defined. The
simplest case is NAME, which is a simple string label, for instance:

NAME = ’Custom Module’

The other variables are in fact classes that contain the specification
of each individual parameter needed by the module. Examples of the
implementation of such classes are given in the following sections.

2.2 Module general properties

Module general properties are not associated to specific entities in
a Rocky UI as are the other types of properties described in the
following sections. Therefore, these properties are displayed in the

© 2022, esss - all rights reserved

 api : solver manual 10
ROCKY

Data Editors panel associated to the module itself, when it is selected

in the Data panel, as shown in the example of Figure 2.1.
An example of the specification of general parameters for a
fictitious module is shown below:

@data_model(icon=None, caption=NAME)
class CustomGeneralParameters:
custom_boolean = Boolean(value=True, caption=’Custom Boolean Parameter’)
custom_quantity = Quantity(value=0.0, unit=’m’, caption=’Custom Quantity’)
custom_string = String(value=’string’, caption=’Custom String’)

This class defines three parameters, each one of a different type.

The first one is a boolean parameter, the second one is a numeric
parameter, and the third one is a string. When the module is activated
in the Rocky UI, these parameters are displayed in the Data Editors
panel, as shown in Figure 2.1. When setting up a project, users can
define proper values for these parameters, and Rocky will deliver
them to the module when the simulation starts. In the specification
of the parameters, it must be indicated the default value (the first
argument) and the caption that must displayed in the UI (the last
argument). Additionally, the corresponding unit must be specified for
numeric parameters (the second argument). Units must be specified
as strings representing valid units. Although Rocky supports different
unit systems, it is advisable that custom modules define parameters
1
Examples of strings representing valid
using only units from the SI system.1 Otherwise, all necessary unit SI units are: ’m’, ’s’, ’kg’, ’K’, ’N’,
’J’, ’Pa’, ’m/s’, ’m/s2’, etc.

Figure 2.1: General module parameters

in the Data Editors panel of the Rocky
UI.

© 2022, esss - all rights reserved

 api : solver manual 11
ROCKY

conversions will have to be handled by the custom C++ code that

implements the module’s functionality.
Another possibility of specifying parameters is through lists, which
are useful when a module must allow users to create a number of
similar parameters. These lists are displayed in the UI as tables, as
shown in the example of Figure 2.2. Rows in these tables can be
added or removed interactively using the tools provided by the UI. In
order to specify a list as the one in the example, the following code
must be included:

@data_model(icon=None, caption=NAME)
class CustomGeneralParameters:
custom_list = List(item_class=CustomListSpecs, caption=’Custom List’)

Figure 2.2: General list displayed as a

table in the Rocky UI.

Here, CustomListSpecs is a class that includes the specification of

the parameters in a row of the table. It is possible to specify any
number of parameters per row, belonging to any of the three simple
types mentioned above: numeric, boolean or string. The parameters
in the Figure 2.2 example are specified as follows:

© 2022, esss - all rights reserved

 api : solver manual 12
ROCKY

@data_model(caption=’ListItem’)
class CustomListSpecs:
custom_list__boolean = Boolean(value=True, caption=’Boolean’)
custom_list_quantity_1 = Quantity(value=0.1, unit=’s’, caption=’Quantity 1’)
custom_list_quantity_2 = Quantity(value=0.2, unit=’m’, caption=’Quantity 2’)

2.3 Module material properties

A module can add custom properties to materials apart from the ones
defined by default in Rocky. The specification of these new properties
must follow the pattern described in the previous section for the
general module parameters. The difference is that the custom material
properties will be displayed in the Data Editors panel associated to
each one of the materials defined in a project, as shown in the example
of Figure 2.3.

Figure 2.3: Module material properties

displayed in the Rocky UI.

The specification of the parameters shown in the example is defined

as follows:

© 2022, esss - all rights reserved

 api : solver manual 13
ROCKY

@container_model()
class CustomMaterialProperties:
mat_prop_1 = Quantity(value=0.1, unit=’m’, caption=’Custom Material Property 1’)
mat_prop_2 = Quantity(value=300.0, unit=’K’, caption=’Custom Material Property 2’)

2.4 Module materials interactions properties

Rocky can associate module parameters to materials interactions so
that each pair of materials can have different values. The specification
of these parameters is similar to the one described in section 2.2 for the
general parameters. In principle, it is possible to specify parameters
of any of the types mentioned there.
The materials interactions parameters of a module are displayed
as shown in Figure 2.4, below the built-in materials interactions
parameters in the Data Editors panel.

Figure 2.4: Module materials interaction

parameters displayed in the Rocky UI.

© 2022, esss - all rights reserved

 api : solver manual 14
ROCKY

The specification of the parameters shown in the example is defined

as follows:

@container_model()
class CustomInteractionProperties:
custom_mi_quantity_1 = Quantity(value=0.0, unit=’Pa’, caption=’Custom Quantity 1’)
custom_mi_quantity_2 = Quantity(value=7.0, unit=’-’, caption=’Custom Quantity 2’)

2.5 Module geometry properties

When Rocky associates module parameters to each one of the
individual boundaries in a project, those parameters are called
geometry properties. In the Rocky UI, they are displayed in the
Data Editors panel as shown in Figure 2.5, when an individual
geometry is selected in the Data panel.

Figure 2.5: Module geometry properties

displayed in the Rocky UI.

Parameters of any of the types described in section 2.2 (numeric,

boolean, string or list) can be defined. The corresponding specification
of the parameter included in the example is defined as follows:

© 2022, esss - all rights reserved

 api : solver manual 15
ROCKY

@container_model()
class CustomGeometryProperties:
custom_property = Quantity(value=0.0, unit=’N’, caption=’Custom Geometry Property’)

2.6 Module particle group properties

When this type of property is defined in a module, different values
can be associated to every particle group in a project. In the Rocky UI,
when a specific particle group is selected in the Data panel, a new
sub-tab Modules must appear in the Data Editors panel, including the
custom particle group’s properties defined for all active modules in
the project. An example is shown in Figure 2.6. As with other cases,
parameters of any of the basic types can be defined (numeric, string,
boolean or list). The specification of the parameter in the example is
defined as follows:

@container_model()
class CustomParticleGroupProperties:
custom_pg_property = Quantity(value=0.0, unit=’K’,
caption=’Custom Particle Group Property’)

Figure 2.6: Module particle group prop-

erties displayed in the Rocky UI.

© 2022, esss - all rights reserved

 api : solver manual 16
ROCKY

2.7 Module particle input properties

Rocky supports the ability to associate custom values to every particle
in a simulation. In Rocky, these values are associated to special
variables called particle scalars. They can be used to store particle-
related data calculated by the module during the execution of a
simulation. When it is necessary to assign a specific initial value to
those particle scalars at the moment particles enter the simulation, a
particle input property can be defined. In this way, Rocky will include
in the Data Editors panel corresponding to a Input an additional sub-
tab for defining module-specific particle input data, as shown in
Figure 2.7 for a Continuous Injection Input . An identical sub-tab will
be included also for a Volume Fill Input . On the other hand, for a
Custom Input , this same information will appear at the bottom of the
corresponding tab, in a section labeled with the name of the module.
The values of the parameters defined in that section will be applied to
all particles in the associated particle group, since it is not possible to
associate individual values per particle as it is done with the built-in
particle properties.

Figure 2.7: Custom scalar displayed in

the Rocky UI with the initial value set in
the module’s particle-input properties
sub-tab.

© 2022, esss - all rights reserved

 api : solver manual 17
ROCKY

The corresponding specification of the particle input property for

the example shown in Figure 2.7 is defined as follows:

@container_model()
class CustomParticleInputProperties:
custom_scalar = ScalarProperties(
value=1.0, unit=’kg’, caption=’Custom Scalar’, output=True, input=True
)

A specification like the one shown above defines both a new particle
scalar variable and a custom particle input property. As shown in
Figure 2.7, in this way users will be able to enter the initial value of the
new particle scalar variable through the Rocky UI.2 The last argument 2
If the initial values are supposed to
be always zero or if more granularity is
input=True in the scalar variable specification enables that option. needed in the initial values, users may
The other additional argument, output=True, instructs Rocky that the choose not to define a particle scalar
variable through the Python specifica-
values of the new particle scalar must be stored in disk throughout tion file. Instead, that can be done
directly from the C++ code, as in the
a simulation, and be able to be displayed in a 3D view window at
example provided in chapter 5.
output times, as shown in Figure 2.7.

2.8 Specification of custom models

One of the main motivations for developing custom modules is to
add new models and capabilities to Rocky. Currently, most of the
categories of models are customizable using the Rocky API : Solver.
Table 2.1 summarizes all categories of models that can be implemented
in the current version of Rocky through custom modules.
As mentioned in section 2.1, the module specification file must
inform Rocky which models the module is actually implementing.
Based on this specification, Rocky will either override built-in models
in some categories or add the implemented custom models to the list
of available built-in models in other categories. In order to specify
that a module will implement a custom model, the specification class
must include an attribute member with a predefined name, which
must correspond to a given model category. The second column
of Table 2.1 lists all attribute names recognized by Rocky as model
categories.
The following is an example of the specification of a module
that implements a custom contact model, including the normal and
tangential components of the contact force:

© 2022, esss - all rights reserved

 api : solver manual 18
ROCKY

class CustomModuleSpecs(RockyAddinSpecs):

name = ’Custom Module Example’

model = CustomGeneralParameters

normal_force_model = CustomModel

tangential_force_model = CustomModel

def CreateAddin(cls):
return cls.CreateDynamicAddin(Path(__file__).parent, ’custom_module_name’)

Model category Class attribute Behavior

Contact force, normal component normal_force_model override

Contact force, tangential component tangential_force_model override

Rolling resistance moments rolling_resistance_model override

Adhesion force adhesion_model override

Joint mechanics in flexible particles 2 joint_model addition

Discrete breakage of flexible particles joint_breakage_model addition

Impact energy for instantaneous breakage impact_energy_model override

Instantaneous breakage of rigid polyhedral particles instantaneous_breakage_model addition

Distribution of fragment sizes for instantaneous fragments_size_distribution_model addition

breakage

Wear of surfaces due particle collisions geometries_wear_model addition

Conduction heat transfer rate at contacts heat_conduction_model override

Integration of the particle energy equation 2 thermal_integration_model override

CFD coupling, drag force cfd_drag_law_model addition

CFD coupling, lift force cfd_lift_law_model addition

CFD coupling, virtual mass force cfd_virtual_mass_law_model addition

CFD coupling, flow-induced torque cfd_torque_law_model addition

CFD coupling, convection heat transfer rate cfd_convection_law_model addition

Table 2.1: Class attributes associated to

customizable model categories in Rocky.

© 2022, esss - all rights reserved

 api : solver manual 19
ROCKY

Currently it is not possible to associate properties to a custom

model itself, therefore CustomModel in the example above can be an
empty class, defined as:

@container_model()
class CustomModel:
pass

As mentioned earlier, there are two possible ways in which the

Rocky UI may treat a custom model:

• For model categories with global scope, like contact force models,
Rocky will override any other model in the category if a module
that implements a custom model in that category is enabled in
a project. In that situation, all calculations related to the model
category will be performed by the code in the custom module.
As an illustration, Figure 2.8 shows how the contact force model
categories are displayed in the Physics panel when the module
specified by the previous code example is turned on in the project.
When this situation occurs, it won’t be possible to select any other
model in those categories until the referred module is turned off.
All model categories that behave in this way are marked with the
word "override" in the third column of Table 2.1.

Figure 2.8: Example of custom models

overriding other models in the Rocky
UI.

• For model categories with scope per particle group or geometry,

Rocky will add the custom model implemented by a module to
the list of available models in the category. This can be observed in
the example shown in Figure 2.9, in which a custom joint model

© 2022, esss - all rights reserved

 api : solver manual 20
ROCKY

implemented by a module named Custom Module Example is listed

along with the built-in joint models. All model categories that
behave in this way are marked with the word "addition" in the
third column of Table 2.1.

Figure 2.9: Example of a custom model

being added to the available models in
a category.

Although any module could in principle include the implemen-

tation of several custom models,3 it is advisable to restrict only one 3
There is no restriction in the Rocky
API : Solver regarding the number of
custom model per module. The exception to this rule would be custom models that a module may
those models that have strong interdependence or that may share implement, as long as all of them belong
to different model categories.
data between them. The typical example of the former case is the
trio formed by the normal contact force, the tangential force and the
impact energy models, in which the second one depends on the first,
and the third one may depend on the other two. An example of the
latter case is the pair of models instantaneous breakage and fragment
size distribution, in which the first one can calculate custom data
needed by the second one.

2.9 Specification of variable properties

Since v2022R1, the Rocky API : Solver gives developers the ability of
setting values of selected physical properties during a simulation. In
that way, properties that normally would have constant values during
a whole simulation become variable properties that may depend on
time, position or other simulation variables.

© 2022, esss - all rights reserved

 api : solver manual 21
ROCKY

A module that will calculate and set values of such variable

properties must indicate in the specification file which properties
it will override. An example of how that specification must be done
is shown in the following code snippet:

class CustomModuleSpecs(RockyAddinSpecs):

name = ’Custom Properties Example’

model = CustomGeneralParameters

particle_material_properties = ParticleVariableProperties

triangle_material_properties = TriangleVariableProperties

def CreateAddin(cls):
return cls.CreateDynamicAddin(Path(__file__).parent, ’custom_module_name’)

The two specification keys particle_material_properties and

triangle_material_properties indicate that the module will over-
ride material properties affecting particles and boundary triangles.
The Table 2.2 lists the four categories of properties whose values
can be overridden by custom modules, indicating the corresponding
specification keys that must be used.

Category of properties Specification key

Material properties used by particles particle_material_properties

Material properties used by boundaries triangle_material_properties

Material interaction properties used in particle-to-particle particle_material_interaction_properties

contacts
Material interaction properties used in particle-to-boundary triangle_material_interaction_properties
contacts
Geometry properties geometry_triangle_properties

Table 2.2: Specification keys for different

categories of properties.

Besides indicating the categories of properties, the module must

specify which individual properties on each category will be
overridden. This must be done by defining additional classes, as
indicated in the following code snippets:

© 2022, esss - all rights reserved

 api : solver manual 22
ROCKY

@container_model()
class ParticleVariableProperties:
thermal_conductivity = ThermalConductivity
specific_heat = SpecificHeat

@container_model()
class TriangleVariableProperties:
thermal_conductivity = ThermalConductivity

Regarding the properties for particles, the first snippet code above
indicates that the thermal conductivity and the specific heat will be
overridden by values stored in particle scalars that Rocky will define
internally. By specifying that, the module is taking responsibility for
setting values of those properties for every particle in a simulation.4 4
That implies that values specified
through the Rocky UI for those proper-
Table 2.3 lists all the material properties associated to particles that ties will be ignored by the Rocky solver.
can be overridden by custom modules in the current version of Rocky.

Type of property Specification key Rocky’s internal scalar

Thermal conductivity thermal_conductivity ThermalConductivity

Specific heat specific_heat SpecificHeat

Poisson’s ratio poisson_ratio PoissonRatio

Table 2.3: Particle material properties

whose values may be overridden by
custom modules.
Similarly, the second code snippet shown above indicates that the
module will replace also the thermal conductivity values specified for
materials associated to boundaries. In that way, the constant value
specified normally for a whole boundary will be effectively replaced
by a set of values, one for each triangle making up a boundary, that
the module will have to specify within the C++ code associated to it.
Rocky will use internally a triangle scalar for storing the values of
each one of the properties that the module will override. Table 2.4
lists the boundary properties that a custom module can redefine as
variable properties in the current version of Rocky.
The Rocky API : Solver also supports the substitution of the
material interaction properties indicated in Table 2.5. In that

© 2022, esss - all rights reserved

 api : solver manual 23
ROCKY

Type of property Specification key Rocky’s internal scalar

Thermal conductivity thermal_conductivity ThermalConductivity

Poisson’s ratio poisson_ratio PoissonRatio

Table 2.4: Boundary material proper-

ties that may be overridden by custom
modules, setting values per boundary
case, the constant values originally specified for those proper- triangle.
ties are replaced by a set of values, each one for a particle-to-
particle contact or a particle-to-boundary contact, which Rocky
will store internally in contact scalars. The specification of the
overriding of material interaction properties is equivalent to the
one shown previously for material properties. The main differ-
ence is that it uses particle_material_interaction_properties or
triangle_material_interaction_properties as specification key, as
indicated in Table 2.2.

Type of property Specification key Rocky’s internal scalar

Coefficient of restitution restitution_coefficient Restitution Coefficient

Coefficient of static friction static_friction StaticFriction

Coefficient of dynamic friction dynamic_friction DynamicFriction

Table 2.5: Material interaction properties

whose values may be overridden by
custom modules, for both particle-to-
The Rocky API : Solver also allows developers to override the particle and particle-to-boundary con-
tacts.
temperature prescribed per geometry, replacing it by a set of
temperature values per triangle. As shown in Table 2.6, currently
this is the only geometry property that is enabled to be replaced by a
custom module. An example is presented later on in section 5.3 that
shows how a module can perform that replacement.

Type of property Specification key Rocky’s internal scalar

Temperature temperature Temperature

Table 2.6: Geometry properties whose

values may be overridden by custom
modules.

© 2022, esss - all rights reserved

 api : solver manual 24
ROCKY

2.10 The .plugin file

In addition to the Python file containing an IPlugin subclass, every
module needs a .plugin file that contains metadata about the module
itself. Most of this metadata is not used by Rocky and serves
informational purposes for module users only. However, the file
itself is necessary because it is how the application discovers the
module at runtime.
The file is written in a configuration language similar to the INI
format used in Microsoft Windows configuration files. Here’s a
sample of its contents and a description of the fields:

1 [Core]
2 Name = Sample Module
3 Module = sample_module
4

5 [Documentation]
6 Author = Module Author
7 Version = 1.0
8 Website = www.example.com
9 Description = A short description of the module’s functionalities.
10 You can span multiple lines by indenting after the first one, like this.

where:

• Name is the human-readable name of the Module, and should match

the value provided in the specification class (section 2.1).

• Module is the name of the Python file that contains the IPlugin
subclass, without the .py extension.

• Author is the name of the module’s author.

• Version is the version of the module itself, which is used when

updating the module with new features and bug fixes (see section
2.11).

• Website is the website or email, used as contact information.

• Description is a free-form short description of the module’s

purpose and features.

See Section 5.1 for an example plugin file.

© 2022, esss - all rights reserved

 api : solver manual 25
ROCKY

2.11 Module version

Every module has two versions: one "explicit" version, defined by the
module author in its .plugin file (section 2.10), and the version of the
SDK for which the module was built. While Rocky doesn’t impose
any kind of semantics on the author-defined version, it can be used
to convey to module users the expected stability and completeness of
modules.
One suggestion is to use semantic versioning when defining a
module’s version. Briefly, the module can follow a "X.Y.Z" format,
where:

• Increment the major version X when your module changes in a

way that is incompatible with previous versions;

• Increment the minor version Y when your module gains new

features in a backwards-compatible way;

• Increment the patch version Z when your make backwards-

compatible bug fixes only.

2.11.1 Migrating between module versions

When a module is changed in a way that makes the new specification

incompatible with the old one, the author can write a function to
migrate module properties defined in the old format to the new one.
This can happen, for example, when a Rocky project containing data
saved in the old specification is opened when the new specification is
available.
The module author can indicate that the specification handles
these migrations by implementing the following function in their
specification subclass:

@container_model()
class CustomModuleSpecs(RockyAddinSpecs):
...
@classmethod
def MigrateProperties(self, previous, current):

where previous and current contain data related to the previous

and current versions of the module, respectively. Each object contains
the following attributes:

© 2022, esss - all rights reserved

 api : solver manual 26
ROCKY

• addin_version is the version of the module;

• sdk_version is the version of the SDK;

• snapshot is a Python dictionary containing the user-provided

values for the properties described by the module’s specification.

As an example: suppose that the author of CustomModuleSpecs’s

module renamed a material property from old_name to new_name
and updated the module’s version from "1.0.0" to "2.0.0". When
opening an existing project that was originally saved using version
"1.0.0" of the module, the following code would copy the value of the
property called old_name in the previous snapshot to the property
called new_name in the current snapshot, for every material defined in
the project that is being loaded:

@container_model()
class CustomModuleSpecs(RockyAddinSpecs):
...
classmethod
def MigrateProperties(self, previous, current):
if previous.addin_version == ’1.0.0’ and current.addin_version == ’2.0.0’:
previous_materials = previous.snapshot[’material_properties’]
current_materials = current.snapshot[’material_properties’]

for previous_material, current_material in zip(

previous_materials.values(), current_materials.values()
):
current_material[’new_name’] = previous_material[’old_name’]

return True
return False

© 2022, esss - all rights reserved

 api : solver manual 27
ROCKY

3 Solver hooks
The Rocky API : Solver allows users to attach customized C++ code
into strategic points of the code that executes a simulation in Rocky.
At these points, which are named generically as hooks, the Rocky
API : Solver will provide access to data relevant to the intended
operation at that location, and also sometimes the means to send
back data to the solver, in order to modify some specific behavior.
As an illustration, Figure 3.1 shows the position of the main hooks
provided by the Rocky API : Solver in a very simplified flowchart of a
simulation in Rocky.
This section describes the hooks a module can attach to during a
simulation in order to execute custom C++ code. These hooks can be
separated broadly into two groups: the ones that are executed only
once, when Rocky starts or terminates the simulation, and the ones
that are called several times during the simulation, as Rocky updates
the state of the particulate system.

3.1 Initialization and termination hooks

The following hooks are called once, when the simulation starts or
terminates, as shown in the diagram of Figure 3.1.

3.1.1 ROCKY_PLUGIN_CONFIGURE

At this point, Rocky parses the configuration settings of external

modules. This hook is intended for a module to retrieve the custom
input data that was set by the user through the Rocky UI and store
it locally for later use. The specifications for custom input data is
defined by a module through a Python file, as described in chapter 2.

Parameters:  const IRockyPluginData &input_data

Brings all the values of module parameters entered through the Rocky UI.
For a description of the available methods for retrieving the values from
IRockyPluginData, see chapter 6.

© 2022, esss - all rights reserved

 api : solver manual 28
ROCKY

 void *&data
Accepts a generic pointer that is returned back by other hooks. The module may
use this pointer to point to a local struct, in order to be able to access to custom
data in other stages of the simulation.

Figure 3.1: Position of the main hooks

provided by the Rocky API : Solver,
relative to the main operations made
Start during a simulation.
ROCKY_PLUGIN_CONFIGURE
ROCKY_PLUGIN_SETUP
ROCKY_PLUGIN_COMPUTE_TIMESTEP
ROCKY_PLUGIN_INITIALIZE_PARTICLE
ROCKY_PLUGIN_INITIALIZE_TRIANGLE
ROCKY_PLUGIN_NON_DIMENSIONALIZE
ROCKY_PLUGIN_INITIALIZE
ROCKY_PLUGIN_INITIALIZE_CUDA

New timestep

ROCKY_PLUGIN_BEGIN_ITERATION
ROCKY_PLUGIN_BEGIN_ITERATION_CUDA

ROCKY_PLUGIN_PRE_FORCES

Calculation of forces

ROCKY_PLUGIN_POST_FORCES

ROCKY_PLUGIN_PRE_MOVE

Solution of motion equations

ROCKY_PLUGIN_POST_MOVE

YES
Output time?

ROCKY_PLUGIN_PRE_OUTPUT_CUDA_SYNC_DATA
NO
ROCKY_PLUGIN_PRE_OUTPUT

Output

ROCKY_PLUGIN_POST_OUTPUT

NO
Final time?

YES
ROCKY_PLUGIN_TEAR_DOWN
ROCKY_PLUGIN_TEAR_DOWN_CUDA

End

© 2022, esss - all rights reserved

 api : solver manual 29
ROCKY

3.1.2 ROCKY_PLUGIN_SETUP

During the setup, Rocky allocates resources that will be needed during
the simulation. In this hook, a custom module may allocate memory
or other resources for storing custom data.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation. For a list of the
methods associated to IRockyModel, see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.1.3 ROCKY_PLUGIN_COMPUTE_TIMESTEP

When a module implements a custom contact force model, it is

possible that the model will need a special procedure for the
calculation of a stable timestep. If that is the case, this is the hook
where that calculation must be implemented.

Parameters:  IRockyTimestepData &timestep_data

An object with basic methods for accessing material and materials interactions
properties, as well as particle group data, to let users implement a stable time step
calculation. See chapter 6 for a complete description of IRockyTimestepData.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.1.4 ROCKY_PLUGIN_COMPUTE_ADHESIVE_DISTANCES

Deprecated hook. In the current version of the Rocky API : Solver,

adhesive distance values can be set within any hook with access to a
IRockyModel object, by using the set_adhesive_distance method.

3.1.5 ROCKY_PLUGIN_INITIALIZE_PARTICLE

This hook can be used to initialize particle scalars with values different
from zero (the default value when a scalar variable in Rocky is
created). The associated code is executed always in CPU, in a loop
over all active particles in the simulation.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.

© 2022, esss - all rights reserved

 api : solver manual 30
ROCKY

 IRockyParticleHost &particle
An active particle.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.1.6 ROCKY_PLUGIN_INITIALIZE_TRIANGLE

This hook can be used to initialize triangle scalars with values different
from zero (the default value when a scalar variable in Rocky is
created). The associated code is executed always in CPU, in a loop
over all geometry triangles in the project.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 IRockyTriangleHost &triangle
A geometry triangle.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.1.7 ROCKY_PLUGIN_NON_DIMENSIONALIZE

Internally, Rocky treats all variables as dimensionless in order to

minimize roundoff errors. Therefore, all custom parameters defined
in the module must be nondimensionalized at this stage in order to
be used correctly during the later calculations.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation. For the
nondimensionalization process, this object provides dimensional factors for
each one of the fundamental magnitudes and some common derived ones. For a
list of all the methods associated to IRockyModel, see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.1.8 ROCKY_PLUGIN_INITIALIZE

This hook is placed at the point when Rocky sets the initial state of
the simulation. If necessary, the module may use that initial state as a
basis to initialize its own custom data.

© 2022, esss - all rights reserved

 api : solver manual 31
ROCKY

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation. For a list of all
the methods associated to IRockyModel, see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.1.9 ROCKY_PLUGIN_INITIALIZE_CUDA

When a simulation must run in single or multi-GPU, Rocky needs

to allocate memory and copy the initial state of the simulation to
the GPU devices. This hook, called for each enabled GPU device, is
intended for performing those operations with the custom data of a
module.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 void *host_data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.
 int device_id
Identifier of an individual GPU.
 void *&device_data
Accepts a generic pointer associated to the GPU device identified by device_id.
The module must ensure in this hook that this pointer will point to a copy of
the local struct in the GPU device, after allocating memory and performing the
copy operation. Rocky will return back this pointer in all the iteration hooks that
are executed in GPU, in order to be able to access custom data values at those
places.

3.1.10 ROCKY_PLUGIN_TEAR_DOWN

When Rocky terminates a simulation, the module has the opportunity

in this hook to perform final actions, such as deallocate memory used
for custom data, gracefully close resources, and output final remarks
about the simulation.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

© 2022, esss - all rights reserved

 api : solver manual 32
ROCKY

3.1.11 ROCKY_PLUGIN_TEAR_DOWN_CUDA

In this hook the module must free the memory allocated for custom
data in the GPU devices during the execution of ROCKY_PLUGIN_INITIALIZE_CUDA.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 int device_id
Identifier of an individual GPU.
 void *device_data
Accepts a generic pointer associated with the GPU id that is returned back by
other GPU-aware hooks. The module may use it as a mechanism to persist
custom data between GPU devices during the simulation execution.

3.2 General-purpose iteration hooks

These hooks are called on each iteration during the simulation
loop in which the motion of the particles and all the enabled
models are solved. As they are not related to a specific type of
model, these hooks can be used for different purposes, such as
collecting relevant simulation data, calculating useful complementary
magnitudes related to the simulation, pre-processing data needed by
some custom model, etc.

3.2.1 ROCKY_PLUGIN_BEGIN_ITERATION

The code attached to this hook is executed when a new cycle of

calculations is initiated, corresponding to a new timestep, as depicted
in Figure 3.1. At this point, a module may reset custom variables for
a new iteration.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation. For a list of the
methods associated to IRockyModel, see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.2.2 ROCKY_PLUGIN_BEGIN_ITERATION_CUDA

This hook is placed also at the beginning of a new cycle of calculations,

but it is executed on each one of the active GPU devices, when a
simulation runs in GPU.

© 2022, esss - all rights reserved

 api : solver manual 33
ROCKY

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 void *host_data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

 int device_id
Identifier of an individual GPU.
 void *&device_data
The generic pointer pointing to a copy of a local struct in a GPU device,
provided in ROCKY_PLUGIN_INITIALIZE_CUDA.

3.2.3 ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS

The associated custom code will be executed before the calculation

of contact forces, inside a loop over the active frictional contacts.
A closing ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS_END() statement
must be inserted at the end of the custom code block.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyContact &contact
An active frictional contact object. For a complete list of the associated methods,
see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.2.4 ROCKY_PLUGIN_PRE_FORCE_ON_PARTICLES

The associated custom code will be executed before the calculation of

contact forces, inside a loop over the active particles in the simulation.
A closing ROCKY_PLUGIN_PRE_FORCE_ON_PARTICLES_END() statement
must be inserted at the end of the custom code block.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
An active particle object. For a complete list of the associated methods, see
chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

© 2022, esss - all rights reserved

 api : solver manual 34
ROCKY

3.2.5 ROCKY_PLUGIN_PRE_FORCE_ON_JOINTS

The associated custom code will be executed before the calculation of

joint forces, inside a loop over the joints in all active multi-element par-
ticles in a simulation. A ROCKY_PLUGIN_PRE_FORCE_ON_JOINTS_END()
statement must be inserted at the end of the custom code block.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyJoint &joint
An active joint object. For a complete list of the associated methods, see chapter
6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.2.6 ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS

The associated custom code will be executed after the calculation

of contact forces, inside a loop over the active frictional contacts.
A closing ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS_END() statement
must be inserted at the end of the custom code block.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyContact &contact
An active frictional contact object. For a complete list of the associated methods,
see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.2.7 ROCKY_PLUGIN_POST_FORCE_ON_PARTICLES

The associated custom code will be executed after the calculation of

contact forces and the corresponding forces over particles, inside
a loop over the active particles in the simulation. A closing
ROCKY_PLUGIN_POST_FORCE_ON_PARTICLES_END() statement must be
inserted at the end of the custom code block.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
An active particle object. For a complete list of the associated methods, see
chapter 6.

© 2022, esss - all rights reserved

 api : solver manual 35
ROCKY

 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.2.8 ROCKY_PLUGIN_POST_FORCE_ON_JOINTS

The associated custom code will be executed after the calculation of

joint forces, inside a loop over the joints in all active multi-element par-
ticles in a simulation. A ROCKY_PLUGIN_POST_FORCE_ON_JOINTS_END()
statement must be inserted at the end of the associated custom code.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyJoint &joint
An active joint object. For a complete list of the associated methods, see chapter
6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.2.9 ROCKY_PLUGIN_PRE_MOVE_PARTICLES

The associated custom code is executed before Rocky updates the

kinematic state of the particles. At the end of the custom code block,
a closing ROCKY_PLUGIN_PRE_MOVE_PARTICLES_END() statement must
be inserted.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
An active particle object. For a complete list of the associated methods, see
chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.2.10 ROCKY_PLUGIN_POST_MOVE_PARTICLES

The associated custom code is executed after Rocky has updated the
kinematic state of the particles. At this point, updated positions and
velocities for all active particles are available. At the end of the custom
code block, a closing ROCKY_PLUGIN_POST_MOVE_PARTICLES_END()
statement must be inserted.

© 2022, esss - all rights reserved

 api : solver manual 36
ROCKY

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
An active particle object. For a complete list of the associated methods, see
chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

3.3 Hooks associated to specific models

The hooks described in this section must be used only by modules
that add new models to Rocky.

3.3.1 ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS

When a module implements a custom contact model, the calculation

of the normal component of the contact force must be made in the
code attached to this hook.1 The custom calculation implemented 1
Besides that, the module’s specification
file must include the definition of the
here will override any built-in normal contact force model in Rocky. normal_force_model attribute, as ex-
It is mandatory that the attached custom code block be closed with a plained in chapter 2, in order to inform
Rocky that the module implements a
ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS_END() statement. custom normal force model.

Parameters:  IRockyContact &contact

The frictional contact for which the normal force is being calculated.
 IRockyContactIntermediateData& intermediate_data
An object containing intermediate data useful for the calculation of contact forces.
For a list of the available data in this object, please refer to chapter 6.
 IRockyContactOutputData& output_data
The object that will receive the values calculated by a custom contact model and
will deliver them to Rocky.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.2 ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS

When a module implements a custom contact model, the calculation

of the tangential component of the contact force must be made in
the code attached to this hook.2 It is executed always after the 2
Besides that, the module’s specification
file must include the definition of the
calculation of the normal force component, either by a built-in model tangential_force_model attribute, as
or by custom code in ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS (see explained in chapter 2, in order to in-
form Rocky that the module implements
Figure 3.2). Therefore, at this point, a value of the normal component a custom tangential force model.

© 2022, esss - all rights reserved

 api : solver manual 37
ROCKY

of the contact force will be available for the calculation of the

tangential component. If implemented in a module, the calculation
in this hook will override any built-in tangential contact force
model in Rocky. The custom code block must end with a closing
ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS_END() statement.

Parameters:  IRockyContact &contact

The frictional contact for which the tangential force is being calculated.
 IRockyContactIntermediateData& intermediate_data
An object containing intermediate data useful for the calculation of contact forces.
For a list of the available data in this object, please refer to chapter 6.
 IRockyContactOutputData& output_data
An object that will receive the values calculated by a custom contact model and
will deliver them to Rocky.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

Start Figure 3.2: Hooks used for the imple-

mentation of a contact model. The code
associated to the hooks is executed in
the order indicated in this diagram.
New timestep

ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS
ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS
Calculation of forces
ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS
ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS

Solution of motion equations

YES
Output time?

NO

Output

NO
Final time?

YES

End

© 2022, esss - all rights reserved

 api : solver manual 38
ROCKY

3.3.3 ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS

Sometimes a custom contact model will require a special calculation

of the impact energy, which is usually one of the main inputs for an
instantaneous breakage model. If such calculation is required, it must
be implemented in this hook.3 As shown in Figure 3.2, it is always exe- 3
Besides that, the module’s specification
file must include the definition of the
cuted after the calculation of the normal and tangential components of impact_energy_model attribute, as ex-
the contact force, therefore, the availability of values of these forces for plained in chapter 2, in order to inform
Rocky that the module implements a
the impact energy calculation is guaranteed. The custom code block custom impact energy model.
must end with a ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS_END()
statement.

Parameters:  IRockyContact &contact

The frictional contact for which the impact energy is being calculated.
 IRockyContactIntermediateData& intermediate_data
An object containing intermediate data useful for the calculation of contact forces.
For a list of the available data in this object, please refer to chapter 6.
 IRockyContactOutputData& output_data
An object that will receive the values calculated by a custom contact model and
will deliver them to Rocky.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.4 ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS

Besides implementing the calculation of the contact forces, a custom 4

Besides the implementation of the cal-
contact model may optionally calculate and set moments caused by culation of rolling resistance moments
in this hook, the module must include
rolling resistance. This hook, specifically designed for that purpose, is
within its specification file the defini-
executed at the end of the contact model pipeline, as shown in Figure tion of the rolling_resistance_model
attribute, as explained in chapter 2, in
3.2.4 The custom code block associated to this hook must end with a order to inform Rocky that the module
ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS_END() statement. implements a custom rolling resistance
model.

Parameters:  IRockyContact &contact

The frictional contact for which the rolling resistance moments must be
calculated.
 IRockyContactIntermediateData& intermediate_data
An object containing intermediate data useful for the calculation of contact forces.
For a list of the available data in this object, please refer to chapter 6.
 IRockyContactOutputData& output_data
An object that will receive the values calculated by a custom contact model and
will deliver them to Rocky.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

© 2022, esss - all rights reserved

 api : solver manual 39
ROCKY

3.3.5 ROCKY_PLUGIN_COMPUTE_CONTACT_ADHESIVE_FORCES

When a module implements a custom adhesion model, the adhesive

force acting in an adhesive contact must be calculated in the associated
block of code.5 That custom adhesion model will override any built- 5
Besides that, the module’s specification
file must include the definition of the
in adhesion model in Rocky. The block attached to this hook must adhesion_model attribute, as explained
end with a ROCKY_PLUGIN_COMPUTE_CONTACT_ADHESIVE_FORCES_END() in chapter 2, in order to inform Rocky
that the module implements a custom
statement. adhesion force model.
Normally, the adhesion force has only a component in the normal
direction, but, for special cases, the custom code may calculate
and deliver to Rocky a tangential component of the adhesion force
as well. On the other hand, by convention in Rocky, adhesion
forces are oriented in the same way that contact forces are oriented.
Consequently, an attractive adhesion force must be prescribed with a
negative sign.

Parameters:  IRockyContact &contact

The adhesive contact for which the adhesive force is being calculated.
 IRockyAdhesionOutputData &output_data
An object that will receive the values of the calculated components of the
adhesion force and will deliver them to Rocky. It is mandatory to set the normal
component of the adhesion force, but the tangential component is optional.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.6 ROCKY_PLUGIN_COMPUTE_JOINT_FORCES

A module implementing a custom joint model must include the

calculation joint forces and moments in this block of code, based
6
Besides that, the module’s specification
file must include the definition of the
on the linear and angular joint deformations.6 Currently, the joint_model attribute, as explained in
chapter 2, in order to inform Rocky that
implementation of custom joint models is supported only for flexible the module implements a custom joint
fibers and shells. model.

The block of code implementing a custom joint model must end

with a ROCKY_PLUGIN_COMPUTE_JOINT_FORCES_END() statement.

Parameters:  IRockyJoint &joint

The joint for which the forces and moments are being calculated.
 IRockyJointOutputData &output_data
An object that will receive the values of the forces and moments and will deliver
them to Rocky.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

© 2022, esss - all rights reserved

 api : solver manual 40
ROCKY

3.3.7 ROCKY_PLUGIN_COMPUTE_JOINT_BREAKAGE

This hook must be used to implement a new criterion of discrete

breakage for multi-element flexible particles.7 If implemented, the 7
Besides that, the module’s specification
file must include the definition of the
associated code will be executed in a loop traversing the joints of all joint_breakage_model attribute, as ex-
the multi-element particles enabled to break, after the calculation of plained in chapter 2, in order to inform
Rocky that the module implements a
joint forces and moments. When the custom criterion for breakage custom discrete breakage criterion.
is satisfied, the boolean parameter that Rocky passes to the hook,
broken, must be set to true. Only in this way Rocky will then disable
the joint, effectively breaking up the link between the previously
connected elements.
Currently, custom criteria for joint breakage is supported only
for flexible fibers and shells. In the specific case of shells, a custom
breakage criterion will be evaluated only at the center point of a
joint. Therefore, when that criterion is satisfied, the joint will break
instantaneously and completely. This behavior is different from the
built-in joint breakage models in Rocky, in which a period of partial
breakage may exist before the joint fully breaks, as described on the
DEM Technical Manual.
The associated code block that implements a joint breakage crite-
rion must end with a ROCKY_PLUGIN_COMPUTE_JOINT_BREAKAGE_END()
statement.

Parameters:  IRockyJoint &joint

The joint that will be checked for breakage.
 bool &broken
Its value must be set to true if the joint is supposed to break.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.8 ROCKY_PLUGIN_INITIALIZE_INSTANTANEOUS_BREAKAGE

The code associated to this hook will be executed during the

initialization of the simulation and after the generation of every
new fragment at an instantaneous breakage event. It can be used
for setting initial values for variables that a custom instantaneous
breakage model may need.

Parameters:  IRockyBreakableParticle &breakable_particle

An abstraction of a particle that is able to break by instantaneous breakage. For
a list of the available methods, please see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

© 2022, esss - all rights reserved

 api : solver manual 41
ROCKY

3.3.9 ROCKY_PLUGIN_COMPUTE_INSTANTANEOUS_BREAKAGE

This hook must be used to implement a new criterion for instan- 8

Besides that, the module’s specifica-
tion file must include the definition
taneous breakage.8 If implemented, the associated code will be of the instantaneous_breakage_model
executed in a loop traversing all particles enabled to break, after the attribute, as explained in chapter 2, in
order to inform Rocky that the mod-
calculation of contact forces. At the moment the custom criterion for ule implements a custom instantaneous
breakage criterion.
instantaneous breakage is satisfied, the boolean parameter passed by
reference to the hook, broken, must be set to true. Later on in the
same time iteration, Rocky will execute the fragmentation algorithm
with the active fragment distribution model, for all particles that
have satisfied that condition. The code block that implements a
custom instantaneous breakage criterion must end with a closing
ROCKY_PLUGIN_COMPUTE_INSTANTANEOUS_BREAKAGE_END() statement.

Parameters:  IRockyParticle &particle

The particle that will be checked for breakage.
 bool &broken
Its value must be set to true if the calculations indicate that the particle is
supposed to break.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.10 ROCKY_PLUGIN_INITIALIZE_FRAGMENTS_SIZE_DISTRIBUTION

The code associated to this hook will be executed during the

initialization of the simulation and after the generation of every
new fragment at an instantaneous breakage event. It can be used
for setting initial values for variables that a custom fragment size
distribution model may need.

Parameters:  IRockyBreakableParticle &breakable_particle

An abstraction of a particle that is able to break by instantaneous breakage. For
a list of the available methods, please see chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

© 2022, esss - all rights reserved

 api : solver manual 42
ROCKY

3.3.11 ROCKY_PLUGIN_COMPUTE_FRAGMENTS_SIZE_DISTRIBUTION

This hook can be used to implement a new model for the calculation of
the size distribution of fragments in an instantaneous breakage event.9 9
In that case, the module’s specification
file must include the definition of the
It can be used either as a complement to a custom instantaneous fragments_size_distribution_model
breakage criterion or in a standalone module devised to work with attribute, as explained in chapter 2, in
order to inform Rocky that the module
built-in instantaneous breakage models in Rocky. In the latter case, implements a custom fragments size
distribution.
the only constraint is that the calculation must be based on the value
of the t10 parameter, as in most of the built-in models in Rocky.

Parameters:  IRockyBreakableParticle &breakable_particle

An abstraction of a particle that is able to break by instantaneous breakage. For
a list of the available methods, please see chapter 6.
 std::vector<double>& distribution
A vector containing the sizes of the fragments resulting in a breakage event,
arranged in descending order.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.12 ROCKY_PLUGIN_COMPUTE_BOUNDARIES_WEAR

This hook can be used to implement a custom calculation of 10

In that case, the module’s specification
file must include also the definition
the surface wear caused by particle collisions on the boundaries of the geometries_wear_model attribute,
as explained in chapter 2, in order to in-
(geometries) in a simulation.10 The associated code must calculate
form Rocky that the module implements
and deliver to Rocky the volume of material worn from a boundary a custom wear model.

triangle during a simulation timestep in a single particle-boundary

contact. Then, Rocky will collect the worn volumes from all triangles
that make up the boundaries and will execute the algorithm of grid
deformation on them. 11 The associated custom code must be closed 11
For more details about wear simula-
tion in Rocky, please refer to section 2.5
by a ROCKY_PLUGIN_COMPUTE_BOUNDARIES_WEAR_END() statement. in the Rocky DEM Technical Manual.

Parameters:  IRockyContact &triangle_contact

A contact between a particle and a triangle from a wear-enabled boundary.
 double& wear_volume
The module must set in this variable the volume of material worn from the
boundary as a result of the action of the contact forces on the triangle_contact,
during a single timestep.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

© 2022, esss - all rights reserved

 api : solver manual 43
ROCKY

3.3.13 ROCKY_PLUGIN_COMPUTE_CONTACT_HEAT_CONDUCTION

This hook can be used to implement a custom calculation of the heat 12

In that case, the module’s specification
file must include also the definition
transfer rate by conduction between two particles or between a particle of the heat_conduction_model attribute,
as explained in chapter 2, in order to
and a boundary.12 The associated code block must be closed by a
inform Rocky that the module imple-
ROCKY_PLUGIN_COMPUTE_CONTACT_HEAT_CONDUCTION_END() statement. ments a custom contact heat conduction
model.
Parameters:  IRockyDeviceModel &model
General information about the current state of the simulation.
 IRockyContact &contact
The frictional contact at which the heat transfer rate is being calculated.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.14 ROCKY_PLUGIN_COMPUTE_THERMAL_INTEGRATION

This hook can be used to integrate the energy balance equation for a
single particle, in order to update its temperature. 13 This operation 13
In that case, the module’s specification
file must include also the definition
will require the use of the total heat transfer rate to the particle, of the thermal_integration_model at-
calculated in previous steps (by conduction or any other mechanisms tribute, as explained in chapter 2, in
order to inform Rocky that the module
active in the simulation). The associated code block must be closed implements a custom thermal integra-
tion procedure.
by a ROCKY_PLUGIN_COMPUTE_THERMAL_INTEGRATION_END() statement.

Parameters:  IRockyDeviceModel &model

General information about the current state of the simulation.
 IRockyParticle &particle
The particle whose temperature must be updated by integrating the energy
balance equation.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.3.15 ROCKY_PLUGIN_COMPUTE_GEOMETRIES_MOTION

This hook is intended for the implementation of a custom motion

kernel. In Rocky, a motion kernel is responsible for moving geometries
from one location in the domain to another during the simulation. The
code associated to this hook will be executed at every Rocky timestep
during the simulation. To work, the custom motion kernel must
first know which geometries in the Rocky project are available for
motion, which it gets from their Rocky IDs or names. Then at every
timestep, it moves the proper geometries according to the custom

© 2022, esss - all rights reserved

 api : solver manual 44
ROCKY

motion kernel setup. No custom motion setup is done in Rocky;

Rocky only provides in this hook the current position, orientation,
translational and rotational velocities of the geometries and the forces
and moments applied by the particles to the geometries, and then
that information can be taken or not into account to calculate the next
motion for the geometry.

Parameters:  IRockyModel& model

Provides data about the general configuration of a simulation.
 IRockyGeometriesMotionData& motion
A data structure that holds motion information for all geometries in the Rocky
project.
 void* data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a
module’s local struct.

3.4 CFD coupling hooks

The Rocky API : Solver includes a number a hooks intended for
implementing new interaction models between particles and fluid
flow. A custom model can implement one or several of those
models, associating the corresponding code to appropriate hooks.
It is worth noting, though, that the code related to all CFD
coupling hooks used in a module must be grouped inside a block
beginning with ROCKY_PLUGIN_CFD_COUPLING() and ending with
ROCKY_PLUGIN_CFD_COUPLING_END.
The code associated to CFD coupling hooks will have effect only
on both constant and Fluent 1-way coupling modes, as well as on
the Fluent 2-way coupling mode. For details about how the CFD
coupling models are defined in Rocky, please refer to the DEM-CFD
Coupling Technical Manual.

3.4.1 ROCKY_PLUGIN_CFD_COUPLING_DRAG_COEFFICIENT

This hook is intended for the calculation of a custom drag coef-

ficient, which, in turn, Rocky will use to calculate the drag force
acting over a particle.14 This force will be calculated by means 14
In order to inform Rocky that a mod-
ule implements a custom drag coeffi-
of equation (3.5) of the DEM-CFD Coupling Technical Manual. cient calculation, the module’s specifi-
The associated code block must end with a return statement, cation file must include the definition
of the cfd_drag_law_model attribute, as
returning the calculated coefficient value, followed by a closing explained in chapter 2.
ROCKY_PLUGIN_CFD_COUPLING_DRAG_COEFFICIENT_END() statement.

© 2022, esss - all rights reserved

 api : solver manual 45
ROCKY

Parameters:  IRockyParticle &particle

The particle on which the calculated drag force will be applied.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the particle-fluid
interactions. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.2 ROCKY_PLUGIN_CFD_COUPLING_LIFT_COEFFICIENT

This hook is intended for the calculation of a custom lift coeffi-

cient, which, in turn, Rocky will use to calculate the lift force
acting over a particle.15 This force will be calculated by means 15
In order to inform Rocky that a mod-
ule implements a custom lift coefficient
of equation (3.69) of the DEM-CFD Coupling Technical Manual. calculation, the module’s specification
The associated code block must end with a return statement, file must include the definition of the
cfd_lift_law_model attribute, as ex-
returning the calculated coefficient value, followed by a closing plained in chapter 2.
ROCKY_PLUGIN_CFD_COUPLING_LIFT_COEFFICIENT_END() statement.

Parameters:  IRockyParticle &particle

The particle on which the calculated lift force will be applied.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.3 ROCKY_PLUGIN_CFD_COUPLING_VIRTUAL_MASS_COEFFICIENT

This hook is intended for the calculation of a custom virtual mass coef-
ficient, which, in turn, Rocky will use to calculate the virtual mass and
the associated force acting over a particle.16 This force will be calcu- 16
In order to inform Rocky that a mod-
ule implements a custom virtual mass
lated by means of equation (3.65) of the DEM-CFD Coupling Technical calculation, the module’s specification
Manual. The associated code block must end with a return statement, file must include the definition of the
cfd_virtual_mass_law_model attribute,
returning the calculated coefficient value, followed by a clos- as explained in chapter 2.
ing ROCKY_PLUGIN_CFD_COUPLING_VIRTUAL_MASS_COEFFICIENT_END()
statement.

Parameters:  IRockyParticle &particle

The particle on which the calculated virtual mass force will be applied.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.

© 2022, esss - all rights reserved

 api : solver manual 46
ROCKY

 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.4 ROCKY_PLUGIN_CFD_COUPLING_TORQUE_COEFFICIENT

This hook is intended for the calculation of a custom torque coefficient,

which, in turn, Rocky will use to calculate the flow-generated torque
acting over a particle.17 This force will be calculated by means 17
In order to inform Rocky that a mod-
ule implements a custom torque coeffi-
of equation (3.78) of the DEM-CFD Coupling Technical Manual. cient calculation, the module’s specifica-
The associated code block must end with a return statement, tion file must include the definition of
the cfd_torque_law_model attribute, as
returning the calculated coefficient value, followed by a closing explained in chapter 2.
ROCKY_PLUGIN_CFD_COUPLING_TORQUE_COEFFICIENT_END() statement.

Parameters:  IRockyParticle &particle

The particle on which the calculated torque will be applied.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.5 ROCKY_PLUGIN_CFD_COUPLING_NUSSELT_NUMBER

This hook is intended for the calculation of a custom Nusselt number,

which, in turn, Rocky will use to calculate the heat transfer rate
between a particle and the surrounding fluid.18 The heat transfer 18
In order to inform Rocky that a
module implements a custom Nusselt
coefficient based on the calculated Nusselt number will be obtained number calculation, the module’s spec-
by means of equation (4.3) of the DEM-CFD Coupling Technical ification file must include the defini-
tion of the cfd_convection_law_model
Manual. Afterwards, the convective heat transfer rate will be attribute, as explained in chapter 2.
calculated with equation (4.2) of the referred manual. The code
block associated to this hook must end with a return statement,
returning the calculated coefficient value, followed by a closing
ROCKY_PLUGIN_CFD_COUPLING_LIFT_COEFFICIENT_END() statement.

Parameters:  IRockyParticle &particle

The particle to which the calculated the convective heat transfer rate is referred.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

© 2022, esss - all rights reserved

 api : solver manual 47
ROCKY

3.4.6 ROCKY_PLUGIN_PRE_FORCE_ON_FLUID

The code associated to this hook will be executed before the

calculation of the CFD coupling coefficients and the corresponding
forces and heat transfer rates. It can be used for performing some pre-
calculation needed in later hooks. The associated code block must be
closed with a ROCKY_PLUGIN_PRE_FORCE_ON_FLUID_END() statement.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
The particle to which the CFD coupling interaction properties are referred.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.7 ROCKY_PLUGIN_POST_FORCE_ON_FLUID

The code associated to this hook will be executed after the calculation
of the CFD coupling coefficients and the corresponding forces and
heat transfer rates. The associated code block must be closed with a
ROCKY_PLUGIN_PRE_FORCE_ON_FLUID_END() statement.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
The particle to which the CFD coupling interaction properties are referred.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.8 ROCKY_PLUGIN_PRE_MOVE_ON_FLUID

The code associated to this hook will be executed after the calculation
of the CFD coupling forces and heat transfer rates, but before solving
the motion equations for the particles. The associated code block must
be closed with a ROCKY_PLUGIN_PRE_MOVE_ON_FLUID_END() statement.

© 2022, esss - all rights reserved

 api : solver manual 48
ROCKY

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
The particle to which the CFD coupling interaction properties are referred.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.4.9 ROCKY_PLUGIN_POST_MOVE_ON_FLUID

The code associated to this hook will be executed after the calculation
of the CFD coupling forces and heat transfer rates, and after solving
the motion equations for the particles. The associated code block
must be closed with a ROCKY_PLUGIN_POST_MOVE_ON_FLUID_END()
statement.

Parameters:  IRockyDeviceModel &device_model

General information about the current state of the simulation.
 IRockyParticle &particle
The particle to which the CFD coupling interaction properties are referred.
 RockyCFDProperties &cfd
A data structure containing data related to the fluid flow and the interaction
particle-fluid. For list of the available data, please refer to chapter 6.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct with custom data.

3.5 Output hooks

The current version of the Rocky API : Solver includes some hooks
intended for enabling modules to deliver custom data to Rocky in
order to be saved, visualized and post-processed. The output of
custom data can be made only at output times, when Rocky’s own
data is stored in disk as well.

3.5.1 ROCKY_PLUGIN_PRE_OUTPUT_CUDA_SYNC_DATA

When running a simulation in GPU, all custom data is copied to

the GPU devices during the initialization stage and then processed
entirely there. Therefore, when it is required to deliver portions of

© 2022, esss - all rights reserved

 api : solver manual 49
ROCKY

this data to Rocky for visualization and post-processing purposes, it

has to be copied back to the CPU.19 This hook is intended primarily 19
The exception are the scalar vari-
ables added by the module, which are
for performing that operation with custom data. The associated code synchronized and made available for
will be executed at output times, before Rocky performs the output visualization automatically by Rocky.
However, any other custom data that
of its own data, as shown in Figure 3.1. will need to be outputted must be
copied to the CPU within this hook.
Parameters:  IRockyModel &model
Provides data about the general configuration of a simulation.
 void *host_data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE for pointing to a local
struct.

 int device_id
Identifier of an individual GPU.
 void *device_data
The generic pointer pointing to a copy of a local struct in a GPU device,
provided in ROCKY_PLUGIN_INITIALIZE_CUDA.

3.5.2 ROCKY_PLUGIN_PRE_OUTPUT

This hook must be used for performing operations on custom data

that need to be done before Rocky begins the writing of output data
on disk. An operation that may be done within this hook is the update
of the datasets that are used to store data that Rocky will display as
time curves and cross-plot curves.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

3.5.3 ROCKY_PLUGIN_POST_OUTPUT

This hook must be used for performing simple operations on custom

data after an output has been made, such as resetting counters or
accumulators.

Parameters:  IRockyModel &model

Provides data about the general configuration of a simulation.
 void *data
The generic pointer provided in ROCKY_PLUGIN_CONFIGURE, pointing to a module
local struct.

© 2022, esss - all rights reserved

 api : solver manual 50
ROCKY

4 Miscellaneous topics

4.1 CUDA-related macros and specifiers

CUDA is the parallel computing platform used by Rocky to enable
the execution of simulations on CUDA-enabled GPU cards. In order
to work properly on GPU simulations, custom modules must perform
some basic operations of memory management on devices and data 1
Although on GPU simulations most of
the heavy operations are processed on
transfer between CPU and GPU.1 GPU, there are many operations, such
This section describes a set of available CUDA-related macros that as setup, initialization and output, that
are performed always on CPU.
may be used for performing basic memory operations in the code
implementing custom modules. It is worth noting that they must
be used only in the CUDA-related hooks,2 and only when modules 2
Currently, the CUDA-related hooks are
four: ROCKY_PLUGIN_INITIALIZE_CUDA,
are intended to be used on simulations running on GPU. In order to ROCKY_PLUGIN_BEGIN_ITERATION_CUDA,
enable CUDA-related macros and hooks, the .cu file implementing ROCKY_PLUGIN_PRE_OUTPUT_CUDA_SYNC_DATA,
and ROCKY_PLUGIN_TEAR_DOWN_CUDA.
the module functionalities must define the preprocessor macro name
ROCKY_CUDA_API.

4.1.1 CUDA_MALLOC

This macro must be used to allocate a block of memory in a device for

storing custom data. This allocation must be made before any copy
operation of custom data to a device.

Parameters:  device_ptr
A pointer that after successful memory allocation will point to the memory
address in a device at which the custom data will be stored. Prior to its utilization
in the macro, this pointer must be a null pointer, otherwise a runtime error will
be thrown.
 size
An integer value that indicates the number of bytes that must be allocated in the
device.

4.1.2 CUDA_MALLOC_TYPE

A variant of CUDA_MALLOC that, instead of receiving the number of

bytes that must be allocated in the device, receives as parameters

© 2022, esss - all rights reserved

 api : solver manual 51
ROCKY

the type of data that will be stored and the number of elements, if it
happens to be an array.

Parameters:  device_ptr
A pointer that after successful memory allocation will point to the memory
address in a device at which the custom data will be stored. Prior to its utilization
in the macro, this pointer must be a null pointer, otherwise a runtime error will
be thrown.
 count
An integer value that indicates the number of elements of the same type that
will be stored in the allocated memory.
 type
The type of variable that will be stored in the device, which can be a C++ built-in
type or a custom data structure.

4.1.3 CUDA_COPY_H2D

This macro must be used to copy custom data from the host to a
device. Prior to this copy operation, the right amount of memory
must have already been allocated within the device, otherwise a
segmentation fault will occur.

Parameters:  device_ptr
Destination memory address within a device.
 host_ptr
Source memory address within the host.
 count
An integer value that indicates the number of elements of the same type that
will be copied.

4.1.4 CUDA_COPY_D2H

This macro performs the inverse operation of CUDA_COPY_H2D, that is,

it copies data from the device back to the host. This operation may be
needed when processed data must be made available to the host in
order to be saved or delivered to the Rocky UI for visualization.

Parameters:  host_ptr
Destination memory address within the host.
 device_ptr
Source memory address within a device.
 count
An integer value that indicates the number of elements of the same type that
will be copied.

© 2022, esss - all rights reserved

 api : solver manual 52
ROCKY

4.1.5 CUDA_MEMSET

This macro sets a memory block within a device to a given value. It

is commonly used to reset to zero a block of memory that previously
contained some data.

Parameters:  device_ptr
Memory address within the device where the block begins.
 value
The value to be defined for each byte within the memory block.
 count
An integer value that indicates the number of elements of the same type that
currently occupy the memory block.

4.1.6 CUDA_FREE

This macro must be used to free the memory block allocated

previously by CUDA_MALLOC.

Parameters:  device_ptr
Device pointer that points to the memory block that must be freed.

4.1.7 ROCKY_FUNCTIONS

This is a function specifier that enables a function to run on both

CPU and GPU. Its use is mandatory in the declaration of auxiliary
functions that are intended to be called from hooks executed on GPU.3 3
Or from hooks that potentially could
be executed on GPU as well.
This is the case for almost all hooks other than the initialization and
termination hooks.4 4
Initialization and termination hooks
are always executed on CPU.

© 2022, esss - all rights reserved

 api : solver manual 53
ROCKY

5 Rocky module examples

The first section of this chapter provides a step-by-step description
of the implementation of a very simple but fully functional module
using the Rocky API : Solver. The whole process is covered, from the
implementation of all the required source files, until the execution
of the compiled module. The second section describes the code
associated to a custom module that implements a contact model.

5.1 A simple custom module

This section describes the implementation of the code of a simple
module in order to illustrate the use of the Rocky API : Solver. The
example module is called Spherical Region. Its only purpose is to
allow users to define a region of spherical shape inside the simulation
domain, and mark all particles located inside this region at any given
time.
The source files detailed below should be saved in the following
directory structure:

spherical_region/
CMakeLists.txt
spherical_region.cu
spherical_region.plugin
spherical_region.py
spherical_region.pdf

The following sections reproduce and describe the content of

each one of the four source files. For a walk-through example of
setting up and using this simple custom module, refer to Workshop
23: SDK and API:Solver, available at https://support.esss.co/hc/
en-us/articles/360057170272.

© 2022, esss - all rights reserved

 api : solver manual 54
ROCKY

5.1.1 File spherical_region.plugin

1 [Core]
2 Name = Spherical Region
3 Module = spherical_region
4

5 [Documentation]
6 Author = Rocky user
7 Version = 1.0
8 Website = [email protected]
9 Description = Marks particles inside a spherical region

The purpose of this file is to give Rocky general information about

the module. For instance, line 2 defines the name of the module as it
must be displayed in the Rocky UI. Similarly, line 3 gives the name of
the compiled library file of the module in the filesystem.1 The data 1
Section 5.1.6 explains how to generate
such an artifact.
in the block between lines 5 and 9 is displayed within the Info tab
associated to the module in the Rocky UI.

5.1.2 File spherical_region.py

This is a Python file that specifies which are the module parameters
that must be displayed in the Rocky UI.2 When a project is set up in 2
Refer to chapter 2 for a complete
description of how different types of
Rocky and the module is enabled, users will be able to enter values data can be specified by means of this
for all parameters defined in this file, through the Rocky UI. file.

1 from pathlib import Path

2 from rocky20.addins.addin_models import container_model, data_model
3 from rocky20.addins.addin_specs import RockyAddinSpecs
4 from rocky20.addins.addin_types import Quantity
5 from yapsy.IPlugin import IPlugin
6

7 NAME = ’Spherical Region’

8

10 @data_model(icon=None, caption=NAME)
11 class SphericalRegionModel:
12 center_x = Quantity(value=0.0, unit=’m’, caption=’Center Coordinate X’)
13 center_y = Quantity(value=0.0, unit=’m’, caption=’Center Coordinate Y’)
14 center_z = Quantity(value=0.0, unit=’m’, caption=’Center Coordinate Z’)
15 radius = Quantity(value=1.0, unit=’m’, caption=’Sphere Radius’)

© 2022, esss - all rights reserved

 api : solver manual 55
ROCKY

16

17

18 class SphericalRegionSpecs(RockyAddinSpecs):
19

20 name = NAME
21

22 model = SphericalRegionModel
23

24 @classmethod
25 def CreateAddin(cls):
26 return cls.CreateDynamicAddin(Path(__file__).parent, ’spherical_region’)
27

28

29 class SphericalRegionModule(IPlugin):
30 def get_addin_specs(self):
31 return SphericalRegionSpecs

SDK utilities necessary for specifying the module data are imported
in the block between lines 1 and 5. Line 7 defines the name of the
module that Rocky must show in the UI. Beginning at line 10, the
auxiliary class SphericalRegionModel is defined, which includes the
specification of the four parameters that the model needs. They are
the three Cartesian coordinates of the sphere center and the sphere
radius.
Between lines 18 and 26, the SphericalRegioSpecs class is defined,
which in this case includes only the definition of the name of the
module and the specification of the parameters previously included
in the SphericalRegionModel class. Additionally, the CreateAddin
method is defined, which handles the loading of the compiled library
file for the module when the simulation starts.
Finally, at line 29, the definition of the SphericalRegionModule
class is included. Only one method is implemented in this class,
get_addin_specs, which makes available all the specifications made
previously in the file.

5.1.3 File spherical_region.pdf

This is an optional help file that may include usage instructions

and/or technical details about the implementation of the module. If
included, Rocky will automatically link it to a special icon displayed 3
For more details, please refer to Work-
in the UI that will allow users of the module to open the file.3 shop 23: API:Solver.

© 2022, esss - all rights reserved

 api : solver manual 56
ROCKY

5.1.4 File CMakeLists.txt

This file includes compilation, linkage and install instructions in the

CMake language, needed to build the module. Several commands
defined by the Rocky SDK are used in order to simplify this file. The
content of this file must be practically the same reproduced below
for any custom module implemented using the Rocky SDK. Users
only have to replace the actual name of the compiled library at line
3 and define the ROCKY_PLUGINS_PATH environment variable with the 4
For further details about creating an
environment variable in the supported
directory in which the compiled modules must be installed, if this platforms, please refer to Workshop 23:
SDK and API:Solver.
definition has not been made previously.4

1 find_package(RockySDK REQUIRED)
2

3 set(PKG_NAME "spherical_region")
4

5 cuda_add_library(${PKG_NAME} SHARED ${PKG_NAME}.cu)

6 target_link_libraries(${PKG_NAME} ${RockySDK_LIBRARIES})
7

8 set(ASSETS_LIST "${PKG_NAME}.plugin" "${PKG_NAME}.py")

9

10 install_rocky_plugin(${PKG_NAME} ASSETS_LIST)

If the module includes a help pdf file, the line 8 must include this
file in the list of module assets, in the following way:

8 set(ASSETS_LIST "${PKG_NAME}.plugin" "${PKG_NAME}.py" "${PKG_NAME}.pdf")

On the other hand, if for some reason the module must be installed
in a directory different from the one pointed to by the environment
variable ROCKY_PLUGINS_PATH, the following additional line can be
inserted between lines 3 and 5:

4 set(ROCKY_PLUGIN_INSTALLATION_DIR ${CMAKE_CURRENT_SOURCE_DIR}/custom_path/)

where custom_path is the path of the folder where the module must
be installed, relative to the source directory being processed.

© 2022, esss - all rights reserved

 api : solver manual 57
ROCKY

5.1.5 File spherical_region.cu

This file includes the C++ code that implements the intended
functionality of the module during the execution of a simulation.
Every function defined in this file must be executed at strategic points
when a simulation is running in Rocky. These points are defined
via the simulation hooks described in chapter 3, and must therefore
chosen carefully by taking into account what operations the module
must perform and what information provided by Rocky will be
necessary for their execution. In order to interact with Rocky, the API
classes and methods described in chapter 6 must be used.

1 #define ROCKY_CUDA_API
2

3 #include <rocky20/api/rocky_api.h>
4

5 struct ModuleData
6 {
7 double3 sphere_center;
8 double sphere_radius;
9 int scalar_index;
10 };
11

12 ROCKY_PLUGIN("Spherical Region", "0.0.0")

13

14 ROCKY_PLUGIN_CONFIGURE(input_data, data)
15 {
16 ModuleData* module_data = new ModuleData();
17 auto model_properties = input_data.get_model();
18 module_data->sphere_center.x = model_properties.get_double("center_x");
19 module_data->sphere_center.y = model_properties.get_double("center_y");
20 module_data->sphere_center.z = model_properties.get_double("center_z");
21 module_data->sphere_radius = model_properties.get_double("radius");
22 data = static_cast<void *>(module_data);
23 }
24

25 ROCKY_PLUGIN_SETUP(model, data)
26 {
27 ModuleData* module_data = static_cast<ModuleData*>(data);
28 auto scalars = model.get_particle_scalars();
29 module_data->scalar_index = scalars.add("Inside Sphere Flag", "-");
30 }
31

© 2022, esss - all rights reserved

 api : solver manual 58
ROCKY

32 ROCKY_PLUGIN_NON_DIMENSIONALIZE(model, data)
33 {
34 ModuleData* module_data = static_cast<ModuleData*>(data);
35 module_data->sphere_center.x /= model.get_length_factor();
36 module_data->sphere_center.y /= model.get_length_factor();
37 module_data->sphere_center.z /= model.get_length_factor();
38 module_data->sphere_radius /= model.get_length_factor();
39 }
40

41 ROCKY_PLUGIN_INITIALIZE_CUDA(model, host_data, device_id, device_data)

42 {
43 auto h_data = static_cast<ModuleData*>(host_data);
44

45 ModuleData* d_data = nullptr;

46 CUDA_MALLOC_TYPE(d_data, 1, ModuleData);
47 CUDA_COPY_H2D(d_data, h_data, 1);
48 device_data = static_cast<void*>(d_data);
49 }
50

51 ROCKY_PLUGIN_POST_MOVE_PARTICLES(device_model, particle, data)

52 {
53 ModuleData* module_data = static_cast<ModuleData*>(data);
54 auto scalars = particle.get_scalars();
55 int scalar_index = module_data->scalar_index;
56 double3 position = particle.get_centroid_position();
57 double distance = get_norm(position - module_data->sphere_center);
58

59 if (distance < module_data->sphere_radius)

60 scalars.set_scalar(scalar_index, 1.0);
61 else
62 scalars.set_scalar(scalar_index, 0.0);
63 }
64 ROCKY_PLUGIN_POST_MOVE_PARTICLES_END()
65

66 ROCKY_PLUGIN_TEAR_DOWN(model, data)
67 {
68 delete static_cast<ModuleData *>(data);
69 }
70

71 ROCKY_PLUGIN_TEAR_DOWN_CUDA(model, device_id, device_data)

72 {
73 auto d_data = static_cast<ModuleData*>(device_data);
74 CUDA_FREE(d_data);
75 }
76

© 2022, esss - all rights reserved

 api : solver manual 59
ROCKY

77 ROCKY_PLUGIN_END

The directive in line 1 enables the execution of the module in single

or multi-GPU configurations.5 When this line is included, the module 5
This directive may be removed if a
module is intended only for execution
must define a ROCKY_PLUGIN_INITIALIZE_CUDA function in order to in CPU.
allocate memory in the GPU and to copy the module data to the GPU,
as described below. 6
In order to simplify the code, the
In line 5, a custom data structure ModuleData is defined, that will Rocky API : Solver provides the struct
double3 for defining 3D points and 3D
be used to store the data needed by the module. In this case, the vectors. It includes as data members
the three coordinates x, y and z. Spe-
structure includes the coordinates of the center point,6 the radius of cial operators for this struct are also
the sphere and an index to identify the particle scalar that will be defined, for addition, subtraction, and
multiplication by a scalar. Moreover,
used to identify the particles inside the spherical region. the functions dot, cross, and get_norm
In line 12, the name and the version of the module implemented by are also provided, for obtaining the
dot product, the cross product, and the
the code in the file are defined. Afterwards, between lines 14 and 23, norm, respectively.

the code associated to the hook ROCKY_PLUGIN_CONFIGURE is defined.

Here, an instance of the custom struct ModuleData is allocated and
the corresponding pointer is named module_data. Next, the values
of the four module parameters entered through the Rocky UI are
retrieved from the function argument input_data, and assigned to
the corresponding variables in the object pointed by module_data.
Finally, in line 22, this pointer is converted to a void pointer in order
to assign it to the function argument data, which Rocky will store
and make available in subsequent stages of the simulation.
Between lines 25 and 30, the code associated to the hook
ROCKY_PLUGIN_SETUP is defined. As in other preprocessing hooks,
the arguments provided are an IRockyModel object,7 named sim- 7
IRockyModel provides a set of methods
for setting up a custom module. See
ply model, and the void pointer that was defined previously in chapter 6.
ROCKY_PLUGIN_CONFIGURE.8 In this specific case, the only operation 8
In order to have access to the data
performed in this block is to define a particle scalar variable that stored previously, the void pointer must
be converted back into a ModuleData
will be used to mark particles inside the spherical region. In line pointer, as it is done in line 27.
28, the object that handles operations with particle scalars is defined.
Subsequently, in line 29 the custom particle scalar is specified. The
two arguments in the add function are the label that must associated
to the particle scalar in the Rocky UI,9 and the unit.10 After creating 9
For instance, this label will identify
the particle scalar in the list of particle
the particle scalar, the Add function will return an integer index
properties displayed in the Properties
that, in this case, will be stored in module_data->scalar_index. tab, after the simulation processing is
complete.
Any subsequent operation involving that specific particle scalar will
10
In this case it is ’-’, which indicates
require the use of that index. that the variable has no unit associated.

© 2022, esss - all rights reserved

 api : solver manual 60
ROCKY

In order to avoid precision loss because of roundoff errors, Rocky

works internally with dimensionless variables. Therefore, the module
has to nondimensionalize all custom parameters previously defined,
in order to use them in operations involving data coming from the
Rocky solver. This operation is made in the block beginning at line
32, within the ROCKY_PLUGIN_NON_DIMENSIONALIZE hook. In this case
all parameters are lengths, so they are nondimensionalized using the
length factor provided by the corresponding method of the model
object.
Between lines 41 and 49, the module data is copied to GPU
devices. This kind of operation is mandatory when a module is
intended for execution in single or multi-GPU configurations. The
hook ROCKY_PLUGIN_INITIALIZE_CUDA provides two generic pointers
as arguments: host_data and device_data. The first one points to
the object that currently stores the data defined in the previous pre-
processing functions.11 The objective of this function is to allocate a 11
This argument is equivalent to the
argument data in ROCKY_PLUGIN_SETUP,
memory block of the right size in the GPU devices, copy the module ROCKY_PLUGIN_CONFIGURE, etc.
data pointed by host_data to that memory block, and finally assign
to device_data the pointer that points to the beginning of that block.
This is done in lines 46 (memory allocation), 47 (data copy) and 48
(conversion to a generic pointer and assigment device_data).
The only operation performed by the module during the time iter-
ative process is the one implemented in the block beginning at line 51.
This operation is associated to the ROCKY_PLUGIN_POST_MOVE_PARTICLES
hook, which is executed inside a loop over the active particles in the
simulation, after the position and velocities of the particles were
updated in Rocky. In line 57, the distance between the centroid of the
current particle and the center of the spherical region is calculated. If
that distance is less than the region radius, the particle is considered
to be inside the region. The scalar value associated to the particle is
set be equal to 1 in that case, and equal to 0 otherwise. The block is
closed by the ROCKY_PLUGIN_POST_MOVE_PARTICLES_END function call,
during which Rocky takes care of some additional operations needed
to execute the module code correctly.12 12
Any of the functions associated to a
hook executed during the time iterative
Finally, the ROCKY_PLUGIN_TEAR_DOWN hook frees the memory loop must be closed by a similar func-
allocated for the local data structure in the CPU memory area. tion.

The equivalent operation on the GPU memory area is made in the

ROCKY_PLUGIN_TEAR_DOWN_CUDA hook.

© 2022, esss - all rights reserved

 api : solver manual 61
ROCKY

5.1.6 Building procedures

This section shows a way to compile the module spherical_region

described in the previous section.13 13
Based upon which version of the
Rocky SDK is installed, the version tag
of the compiled content may differ from
the examples shown here.
5.1.6.1 Building in CentOS 7

In the conda command prompt that was activated in section 1.1.1.3,

navigate to the spherical_region directory and execute the following
commands:

cmake source/plugins/spherical_region
make install

On successful execution of the above commands, the compiled

content of the spherical_region module is available in the folder
pointed by the ROCKY_PLUGINS_PATH environment variable:

4.5/
spherical_region/
libx_spherical_region.so
spherical_region.plugin
spherical_region.py

5.1.6.2 Building in Windows 10

Open the x64 Native Tools Command Prompt for VS 2017, navigate
to the spherical_region directory and execute the following com-
mands:

cmake -DCMAKE_GENERATOR_PLATFORM=x64 source/plugins/spherical_region

cmake --build . --config Release
cmake -P cmake_install.cmake

On successful execution of the above commands, the compiled

content of the spherical_region module is available in the folder
pointed to by the ROCKY_PLUGINS_PATH environment variable:

© 2022, esss - all rights reserved

 api : solver manual 62
ROCKY

4.5/
spherical_region/
spherical_region.dll
spherical_region.lib
spherical_region.plugin
spherical_region.py

5.1.7 Running the module in Rocky

After having completed successfully all the steps described in

previous sections, the new module will be ready to be executed
in a Rocky simulation. Restart the Rocky application in order for it to
acknowledge the recently created module.
When selecting the Modules item in the Data panel, the name
of the new module must appear in the list of modules recognized
by Rocky, displayed in the Data Editors panel. The activation of the
module in a simulation requires that the corresponding checkbox is
turned on, as shown in Figure 5.1.

Figure 5.1: The new module displayed

in the Data Editors panel.

After the module is activated, a new item with the module name
will be added under the Modules item in the Data panel, as shown
in Figure 5.2. The selection of this item gives access to the general
custom parameters defined in the model section of the specifications

© 2022, esss - all rights reserved

 api : solver manual 63
ROCKY

Figure 5.2: The custom parameters

for the module displayed in the Data
Editors panel.

file spherical_region.py. The default values displayed are those

defined in that file. Users of the module can alter those values at
their convenience. On the other hand, if the Info tab is selected, the
reference data included in the spherical_region.plugin is displayed
in the panel.

Figure 5.3: The module’s Info tab on the

Data Editors panel.

In order to test the module, any new project can be set up in

Rocky and then the Spherical Region module must be enabled, defining
the proper values for the module parameters. After processing the
simulation, the Inside Sphere Flag scalar can be selected in the list of
particle properties in the Properties tab, and visualized in a 3D view
window at any output time. All particles inside the specified spherical
region will have an scalar value equal to 1, as depicted in the example
of Figure 5.4, while particles outside it will have associated a zero
value.

© 2022, esss - all rights reserved

 api : solver manual 64
ROCKY

Figure 5.4: Example of a simulation

processed using the new module.

5.2 A module implementing a custom model

As an example of the implementation of a custom model using
the Rocky API : Solver, this section describes the code associated
to a custom module that implements a contact model, including the
calculation of both components of the contact force, as well as the
calculation of the impact energy.
A contact model may include in the most general case the
calculation of both components of the contact force, and, if necessary,
the calculation of the impact energy during a collision. Usually the
tangential component of the contact force depends on the normal
component, and the impact energy on both of them. Because of that,
they are calculated in a fixed sequence, as shown schematically in
Figure 5.5.
The Rocky API : Solver gives some flexibility regarding the
implementation of custom contact force models. For instance, users
can choose to implement only the normal contact force, combining
it with a built-in tangential force model in Rocky. Or, conversely,
users may implement only the tangential contact force, using as input
the normal contact force calculated by a built-in model in Rocky. In
these cases, users only need to implement whichever force component
they want to customize in their module, then in runtime, Rocky will

© 2022, esss - all rights reserved

 api : solver manual 65
ROCKY

Contact model Figure 5.5: Contact model pipeline in

pipeline Rocky.

Normal contact force

Tangential contact force

Impact energy

calculate the other component with the respective model selected in

the Rocky UI.
On the other hand, users may implement the calculation of both
contact force components within a custom module, including the
calculation of the impact energy as well. Impact energy is used in
Rocky as the main input parameter for the built-in instantaneous
breakage models; therefore, users will need to implement a custom
impact energy calculation only if they intend to use a custom contact
force model along with such breakage models.14 Even in that case, 14
Collision statistics modules and en-
ergy spectra display some statistics
users may choose not to implement the calculation of the impact based on the impact energy as well.
energy. Rocky will use in such situation a standard calculation based
on the impact work, as defined in equation (4.10) of the DEM Technical
Manual.15 15
This will happen also when a module
implements only either a normal or a
The remainder of this chapter will describe the implementation tangential force model.
of a custom module including the calculation of both components
of the contact force and the calculation of the impact energy as well.
The normal and tangential force models included in the module are
simplified versions of two built-in models in Rocky, the Hysteretic
Linear Spring and the Linear Spring Coulomb Limit, respectively.
Moreover, the impact energy calculation included in the module is
the one used in Rocky when the Hysteretic Linear Spring model is
selected as normal contact force.

5.2.1 Module specification file

The following listing reproduces the Python file that includes the
specifications for the custom module, which is named simply as
Contact Model Example.

© 2022, esss - all rights reserved

 api : solver manual 66
ROCKY

1 import sys
2 from pathlib import Path
3 from yapsy.IPlugin import IPlugin
4 from rocky20.addins.addin_models import container_model, data_model
5 from rocky20.addins.addin_specs import RockyAddinSpecs
6 from rocky20.addins.addin_types import Quantity
7

8 NAME = ’Contact Model Example’

9

10

11 @data_model(icon=None, caption=NAME)
12 class CustomGeneral:
13 pass
14

15

16 @container_model()
17 class CustomModel:
18 pass
19

20

21 @container_model()
22 class CustomMaterialInteraction:
23 tangential_stiffness_ratio = Quantity(value=1.0, unit=’-’, caption=’Tangential To Normal Stiffness Ratio’)
24 sliding_velocity_threshold = Quantity(value=0.001, unit=’m/s’, caption=’Sliding Velocity Threshold’)
25

26

27 class ContactModelExampleSpecs(RockyAddinSpecs):
28

29 name = NAME
30

31 model = CustomGeneral
32

33 normal_force_model = CustomModel
34

35 tangential_force_model = CustomModel
36

37 impact_energy_model = CustomModel
38

39 material_interaction_properties = CustomMaterialInteraction
40

41 @classmethod
42 def CreateAddin(cls):
43 return cls.CreateDynamicAddin(Path(__file__).parent, ’contact_model_example’)
44

45

46 class ContactModelExamplePlugin(IPlugin):
47 def get_addin_specs(self):
48 return ContactModelExampleSpec

The only parameters added by the module are two material

interaction properties defined between lines 21 and 24. Both of them

© 2022, esss - all rights reserved

 api : solver manual 67
ROCKY

are used in the tangential contact force calculation. The first one is
the ratio of the tangential stiffness to the normal stiffness, while the
second one is the value of the tangential relative velocity that marks
the onset of the sliding between the colliding entities.
Between lines 33 and 37, the module specifies that it will implement
a custom normal force model, a custom tangential force model and
a custom impact energy calculation. In runtime, Rocky will read
these specifications and will override those model categories, using
instead the custom models implemented by the module, as explained
in section 2.8.

5.2.2 Implementation of the contact model

This section describes the different parts that make up the

custom_model_example.cu file that includes the C++ code that
implements the custom models.

1 #define ROCKY_CUDA_API
2

3 #include <rocky20/api/rocky_api.h>
4

5 struct ModuleMaterialInteraction
6 {
7 double tangential_stiffness_ratio;
8 double sliding_velocity_threshold;
9 };
10

11 struct ModuleData
12 {
13 int ppi_normal, pti_normal;
14 int ppi_tangential_x, pti_tangential_x;
15 int ppi_tangential_y, pti_tangential_y;
16 int ppi_tangential_z, pti_tangential_z;
17

18 ModuleMaterialInteraction* material_interactions;
19 };

The initial part of the file reproduced above includes the definition
of the preprocessor name ROCKY_CUDA_API that enables the compila-
tion of the module in CUDA and, in turn, enables the possibility of the
module being used in a simulation processed on GPU. Subsequently,
between lines 5 and 9, it is defined a local struct that will hold the
values entered through the Rocky UI for the two material interaction
parameters that the module uses. Then, between lines 11 and 19,

© 2022, esss - all rights reserved

 api : solver manual 68
ROCKY

another local struct is defined, that will store the indices attributed
in runtime to the contact scalars that the module will create.16 16
Here ppi stands for particle-particle
index, while pti stands for particle-
Additionally, that struct includes an array to store the values of triangle index.
the custom properties associated to all material interactions in the
project.

21 inline ROCKY_FUNCTIONS void create_contact_scalars(

22 IRockyModel& model, const char* name, const char* unit,
23 int& pp_scalar_index, int& pt_scalar_index)
24 {
25 auto pp_scalars = model.get_particle_contact_scalars();
26 auto pt_scalars = model.get_triangle_contact_scalars();
27

28 pp_scalar_index = pp_scalars.add(name, unit, false);

29 pt_scalar_index = pt_scalars.add(name, unit, false);
30 }
31

32 inline ROCKY_FUNCTIONS double get_contact_scalar_value(

33 IRockyContact& contact, int pp_scalar_index, int pt_scalar_index)
34 {
35 return contact.is_particle_particle_contact()
36 ? contact.get_particle_contact_scalars().get_scalar(pp_scalar_index)
37 : contact.get_triangle_contact_scalars().get_scalar(pt_scalar_index);
38 }
39

40 inline ROCKY_FUNCTIONS void set_contact_scalar_value(

41 IRockyContact& contact, int pp_scalar_index, int pt_scalar_index, double value)
42 {
43 contact.is_particle_particle_contact()
44 ? contact.get_particle_contact_scalars().set_scalar(pp_scalar_index, value)
45 : contact.get_triangle_contact_scalars().set_scalar(pt_scalar_index, value);
46 }

The code block above implements three utility functions that

simplify the handling of contact scalars. They allow to treat in a
unified way, with a single function, both types of contact scalars,
namely particle-to-particle and particle-to-triangle contact scalars.

48 ROCKY_PLUGIN("Contact Model Example", "1.0.0")

49

50 ROCKY_PLUGIN_CONFIGURE(input_data, _data)
51 {
52 auto data = new ModuleData();
53

54 int n_material_interactions = input_data.get_number_material_interactions();

55 data->material_interactions = new ModuleMaterialInteraction[n_material_interactions];

© 2022, esss - all rights reserved

 api : solver manual 69
ROCKY

56

57 for (int i = 0; i < n_material_interactions; ++i)

58 {
59 auto& m_i = data->material_interactions[i];
60 auto input_mi = input_data.get_material_interaction(i);
61

62 m_i.tangential_stiffness_ratio = input_mi.get_double("tangential_stiffness_ratio");
63 m_i.sliding_velocity_threshold = input_mi.get_double("sliding_velocity_threshold");
64 }
65

66 _data = static_cast<void*>(data);
67 }
68

69 ROCKY_PLUGIN_SETUP(model, _data)
70 {
71 auto data = static_cast<ModuleData *>(_data);
72

73 create_contact_scalars(model, "Previous Normal Force", "N", data->ppi_normal, data->pti_normal);

74 create_contact_scalars(model, "Previous Tangential Force X", "N",
75 data->ppi_tangential_x, data->pti_tangential_x);
76 create_contact_scalars(model, "Previous Tangential Force Y", "N",
77 data->ppi_tangential_y, data->pti_tangential_y);
78 create_contact_scalars(model, "Previous Tangential Force Z", "N",
79 data->ppi_tangential_z, data->pti_tangential_z);
80 }
81

82 ROCKY_PLUGIN_INITIALIZE_CUDA(model, host_data, device_id, _device_data)

83 {
84 auto h_data = static_cast<ModuleData*>(host_data);
85 auto d_data = *h_data;
86

87 int size = model.get_number_of_material_interactions();

88 ModuleMaterialInteraction* d_material_interactions = nullptr;
89 CUDA_MALLOC_TYPE(d_material_interactions, size, ModuleMaterialInteraction);
90 CUDA_COPY_H2D(d_material_interactions, h_data->material_interactions, size);
91 d_data.material_interactions = d_material_interactions;
92

93 ModuleData* device_data = nullptr;

94 CUDA_MALLOC_TYPE(device_data, 1, ModuleData);
95 CUDA_COPY_H2D(device_data, &d_data, 1);
96 _device_data = static_cast<void*>(device_data);
97 }
98

99 ROCKY_PLUGIN_TEAR_DOWN_CUDA(model, device_id, device_data)

100 {
101 auto d_data = static_cast<ModuleData*>(device_data);
102 ModuleData data_ptr;
103 CUDA_COPY_D2H(&data_ptr, d_data, 1);
104 CUDA_FREE(data_ptr.material_interactions);
105 CUDA_FREE(d_data);
106 }
107

108 ROCKY_PLUGIN_TEAR_DOWN(model, _data)

109 {

© 2022, esss - all rights reserved

 api : solver manual 70
ROCKY

110 auto data = static_cast<ModuleData*>(_data);

111 delete[] data->material_interactions;
112 delete data;
113 }

The block above includes the associated code to the initialization

and termination hooks. As most of these operations were covered in
chapter 5, they will be described here very briefly.
In the ROCKY_PLUGIN_CONFIGURE hook, the values for the two
module parameters per material interaction, entered through the
Rocky UI, are stored in the array within the module local struct
defined previously. Subsequently, in the ROCKY_PLUGIN_SETUP hook,
contact scalars are created for storing the values of the contact forces
calculated in the module. This storage is necessary because both the
normal and tangential force models being implemented depend upon
the history; therefore, in order to calculate the force values at a given
timestep, the values from the previous timestep are required to be
available.
In the ROCKY_PLUGIN_INITIALIZE_CUDA hook, the local module data
is copied to GPU devices after being allocated the required memory
block there. On the other hand, that memory block is freed in the
ROCKY_PLUGIN_TEAR_DOWN_CUDA hook. An equivalent operation for the
memory allocated in CPU is made in the ROCKY_PLUGIN_TEAR_DOWN
hook.

115 ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS(contact, intermediate_data, output_data, _data)

116 {
117 auto data = static_cast<ModuleData *>(_data);
118 const auto m_i = contact.get_material_interaction();
119

120 const double prev_normal_force = get_contact_scalar_value(contact, data->ppi_normal, data->pti_normal);

121

122 const double restitution_coeff = m_i.get_restitution_coefficient();

123 const double loading_stiffness = contact.get_equivalent_stiffness() * m_i.get_stiffness_multiplier();
124 const double unloading_stiffness = loading_stiffness / (restitution_coeff * restitution_coeff);
125

126 const double overlap = contact.get_overlap();

127 const double delta_overlap = overlap - contact.get_previous_overlap();
128

129 const double elastic_force = overlap * loading_stiffness;

130 const double plastic_force = prev_normal_force + delta_overlap * unloading_stiffness;
131 const double new_normal_force = max(min(plastic_force, elastic_force), 0.0);
132

133 output_data.set_normal_force(new_normal_force);

© 2022, esss - all rights reserved

 api : solver manual 71
ROCKY

134

135 set_contact_scalar_value(contact, data->ppi_normal, data->pti_normal, new_normal_force);

136 }
137 ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS_END()

The block of code above implements a simplified but functional

form of the Hysteretic Linear Spring normal contact force. As this is
a history-dependent model, the needed previous value of the normal
contact force is retrieved from the corresponding contact scalar in
line 120. Subsequently, the stiffnesses corresponding to the loading
and unloading portions of the collision cycle are calculated using the
17
The stiffness value returned by the
get_equivalent_stiffness function is
equations in section 2.1.1.1 of the DEM Technical Manual.17 Both already multiplied by the numerical soft-
ening factor, which is commonly used
stiffness values are multiplied by the Contact Stiffness Multiplier , which for increasing the simulation timestep.
is an advanced material interaction parameter that might be used to For more details about this factor, please
refer to section 5.2.4 of the DEM Techni-
prevent large overlaps in certain specific situations.18 cal Manual.
Using the current overlap value and its variation during the 18
Please refer to the Rocky User Manual
for more details on how to enable this
timestep, two possible values of the normal contact force are parameter in the Rocky UI.
calculated, one located on a loading path and other located on an
unloading path.19 The new normal contact force will be the minimum 19
See the force-overlap diagram in Fig-
ure 2.1 of the DEM Technical Manual.
between those two values, as long it is positive. If that minimum value
is negative, the new normal contact force will be set to zero. In line
133 that new value is passed as argument to the set_normal_force
method of the output_data object. This operation is mandatory,
because only in that way Rocky will become aware of the new force
value calculated by the module. From that point on, Rocky will use
internally that force for solving the particles’ motion equations and
perform all the other operations that may need it.
As a final operation of the normal force calculation, the new normal
contact force value is set also to the corresponding contact scalar in
line 135, in order to preserve it and make it available during the next
time iteration.

139 ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS(contact, intermediate_data, output_data, _data)

140 {
141 auto data = static_cast<ModuleData*>(_data);
142 const auto m_i = contact.get_material_interaction();
143 const auto& module_m_i = data->material_interactions[contact.get_material_interaction_index()];
144

145 const double3 prev_tangential_force = contact.just_started_frictional() ?

146 make_double3(0.0, 0.0, 0.0) :
147 make_double3(get_contact_scalar_value(contact, data->ppi_tangential_x, data->pti_tangential_x),

© 2022, esss - all rights reserved

 api : solver manual 72
ROCKY

148 get_contact_scalar_value(contact, data->ppi_tangential_y, data->pti_tangential_y),

149 get_contact_scalar_value(contact, data->ppi_tangential_z, data->pti_tangential_z));
150

151 const double3 tangential_relative_velocity = output_data.get_tangential_relative_velocity();

152 const double3 tangential_displacement = tangential_relative_velocity * contact.get_timestep();
153

154 const double normal_stiffness = contact.get_equivalent_stiffness() * m_i.get_stiffness_multiplier();

155 const double tangential_stiffness = normal_stiffness * module_m_i.tangential_stiffness_ratio;
156

157 double3 new_tangential_force = prev_tangential_force - tangential_stiffness * tangential_displacement;

158 const double new_tangential_force_norm = get_norm(new_tangential_force);
159 const double coulomb_limit = intermediate_data.get_friction_coefficient() * output_data.get_normal_force();
160

161 if (new_tangential_force_norm > coulomb_limit)

162 {
163 new_tangential_force *= coulomb_limit / (new_tangential_force_norm + SMALL_VALUE);
164 bool sliding = get_norm(tangential_relative_velocity) > module_m_i.sliding_velocity_threshold;
165 output_data.set_sliding(sliding);
166 }
167 else
168 {
169 output_data.set_sliding(false);
170 }
171

172 output_data.set_tangential_force(new_tangential_force);
173 set_contact_scalar_value(contact, data->ppi_tangential_x, data->pti_tangential_x, new_tangential_force.x);
174 set_contact_scalar_value(contact, data->ppi_tangential_y, data->pti_tangential_y, new_tangential_force.y);
175 set_contact_scalar_value(contact, data->ppi_tangential_z, data->pti_tangential_z, new_tangential_force.z);
176 }
177 ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS_END()

The implementation of the Linear Spring Coulomb Limit tangential

force model is made in the code reproduced above.20 The model needs 20
This is a simplified version of the
model implemented in Rocky. Some
material interaction properties defined by both Rocky and the module additional operations are ignored for
itself. Because of that, two material interaction objects are defined the sake of simplicity. For instance,
Rocky introduces correction terms to
in lines 142 and 143 in order to retrieve those property values. Next, take into account the change on the
normal direction and a possible viscous
in line 145, the previous tangential force vector is defined as zero if
dissipation, that this implementation
the current timestep is the first one in the collision, or, otherwise, its does not address.

components are retrieved from custom contact scalars. Subsequently,

the tangential component of the relative velocity at the contact point,
pre-calculated by Rocky, is retrieved, and with it the tangential relative
displacement during the timestep is calculated.
In line 154, the normal stiffness value is retrieved, and with it and
the tangential stiffness ratio, the tangential stiffness is determined in
line 155. Then, in line 157, the possible new value of the tangential
force vector is calculated using equation (2.18) of the DEM Technical
Manual. As in this model the magnitude of the tangential contact
force cannot exceed the so-called Coulomb limit, calculated in line

© 2022, esss - all rights reserved

 api : solver manual 73
ROCKY

159,21 the tangential force is rescaled if that condition is not satisfied, 21

The get_normal_force method used
in line 159 will return the normal contact
in line 163.22 Additionally, the sliding condition is verified in line force value recently calculated in the
164, comparing the magnitude of the relative tangential velocity with ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS
hook. If the module does not implement
the sliding threshold value defined as a material interaction property. a custom normal contact force model,
it will return the force value calculated
The boolean value indicating if the sliding condition is true or false is
internally by Rocky using the active
passed to Rocky using the set_sliding method of the output_data built-in model.
22
SMALL_VALUE is an internal constant in
object, in line 165. In case that the Coulomb limit is not exceeded, the
Rocky, set with value 10−15 , used in line
sliding condition is always false, and that value is set in line 169. 163 to avoid division by zero.

The tangential contact force just calculated is passed also to Rocky

by means of the set_tangential_force method of the output_data
object, in line 172. The specification of both the sliding state and the
tangential force vector is mandatory for a module implementing a
tangential contact force model. As a final step, the components of the
tangential force are stored in the contact scalars previously created,
in order to make available those values in the next time iteration.

179 ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS(contact, intermediate_data, output_data, _data)

180 {
181 const double home_stiffness = contact.get_home_stiffness();
182 const double near_stiffness = contact.get_near_stiffness();
183 const double stiffness_multiplier = contact.get_material_interaction().get_stiffness_multiplier();
184

185 const double normal_force = output_data.get_normal_force();

186 const double3 tangential_force = output_data.get_tangential_force();
187 const double squared_force = normal_force * normal_force + dot(tangential_force);
188

189 output_data.set_home_impact_energy(0.5 * squared_force / (stiffness_multiplier * home_stiffness));

190 output_data.set_near_impact_energy(0.5 * squared_force / (stiffness_multiplier * near_stiffness));
191 }
192 ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS_END()

The module example presented in this chapter includes also the

code for the calculation of the impact energy. This code reproduces
the one implemented in Rocky and used when the Hysteretic Linear
Spring model is active in a simulation. It is based on equation (4.11)
of the DEM Technical Manual. Both the normal and the tangential
contact force values calculated in previous steps, retrieved in lines
185 and 186, are needed in that expression. It actually represents the
impact energy accumulated in the contact since the collision started.
However, Rocky expects as output of the calculation the portions of
that impact energy that are attributed to each colliding entity. Because
of that, in lines 189 and 190, two values of impact energy are set using

© 2022, esss - all rights reserved

 api : solver manual 74
ROCKY

the set_home_impact_energy and set_near_impact_energy methods

of the output_data object, respectively.23 23
The way in which the energy is split
between the two colliding entities is
After the module is built following the steps given in section 5.1.6, defined by equations (4.20) and (4.21)
the module will be available to be used in Rocky. When the Contact of the DEM Technical Manual.

Model Example is enabled in a Rocky project, the models of normal

and tangential forces, besides the impact energy model implemented
on it will override built-in models in those categories. This will be
indicated within the Physics | Momentum tab, which will appear as
shown in Figure 5.6.

Figure 5.6: The normal force, tangen-

tial force and impact energy categories
overriden by the models implemented
in Contact Model Example.

5.3 A module implementing variable properties

As an example of the implementation of modules that override
built-in constant properties in Rocky, this section describes a module
that converts the particle’s thermal conductivity into a function of
the temperature. Additionally, the module makes possible also to
define the temperature of boundaries as a function of the position.
The functional relation for the thermal conductivity that the module
implements is the following:

K p = KO (1 + CL Tp ) (5.1)

where KO and CL are two module parameters and Tp is the particle

temperature. On the other hand, the modules allows to define the
temperature of boundary triangles as a quadratic function of the
x-coordinate:
Tt = TO (1 + CQ xt2 ) (5.2)

© 2022, esss - all rights reserved

 api : solver manual 75
ROCKY

where TO and CQ are two module parameters and xt is the x-

coordinate of the triangle’s centroid.

5.3.1 Module specification file

The following listing reproduces the Python file with the specifications
of the module, which is named as Variable Properties Example.

1 from pathlib import Path

2 from rocky20.addins.addin_models import container_model, data_model
3 from rocky20.addins.addin_specs import RockyAddinSpecs
4 from rocky20.addins.addin_types import Quantity, Temperature, ThermalConductivity
5 from yapsy.IPlugin import IPlugin
6

8 NAME = ’Variable Properties Example’

9

10

11 @data_model(icon=None, caption=NAME)
12 class GeneralProperties:
13 pass
14

15

16 @container_model()
17 class MaterialProperties:
18 k_base_value = Quantity(value=1.0, unit=’W/m.K’, caption=’Thermal Conductivity Base Value’)
19 k_linear_coefficient = Quantity(value=0.0, unit=’1/K’, caption=’Linear Coefficient’)
20

21

22 @container_model()
23 class GeometryProperties:
24 t_base_value = Quantity(value=300.0, unit=’K’, caption=’Temperature Base Value’)
25 t_quadratic_coefficient = Quantity(value=0.0, unit=’1/m2’, caption=’Quadratic Coefficient’)
26

27

28 @container_model()
29 class ParticleMaterialVariableProperties:
30 thermal_conductivity = ThermalConductivity
31

32

33 @container_model()
34 class TriangleVariableProperties:
35 temperature = Temperature
36

37

38 class ModuleSpecifications(RockyAddinSpecs):
39

40 name = NAME
41

42 model = GeneralProperties
43

© 2022, esss - all rights reserved

 api : solver manual 76
ROCKY

44 particle_material_properties = ParticleMaterialVariableProperties
45

46 geometry_triangle_properties = TriangleVariableProperties
47

48 material_properties = MaterialProperties
49

50 geometry_properties = GeometryProperties
51

52

53 @classmethod
54 def CreateAddin(cls):
55 return cls.CreateDynamicAddin(Path(__file__).parent, ’variable_properties_example’)
56

57

58 class VariablePropertiesExampleModule(IPlugin):
59 def get_addin_specs(self):
60 return ModuleSpecifications

Lines 18 and 19 of this file define the two parameters used in

equation (5.1) as material properties. This means that different
values can be entered through the Rocky UI for each one of the
materials defined in a project.24 Similarly, lines 24 and 25 define the 24
However, since the module will define
the thermal conductivity as a variable
two parameters included in equation (5.2) as geometry properties. property for particles exclusively, only
Therefore, different values of these parameters could be specified for parameter values from materials associ-
ated to particles will be effectively used
each geometry in a project. by the module.
The class defined in lines 28 to 30 specifies which material
properties associated to particles will be overridden by the module. In
this case, the thermal conductivity is the only property specified. That
property is associated to an particle scalar variable defined internally
in Rocky (ThermalConductivity) which the solver will use to store
the values calculated by the module. A similar specification is made
between lines 30 and 35 for the temperature of the boundary triangles.
For more details about the specification of variable properties, please
refer to section 2.9.

5.3.2 Module implementation

This section describes the C++ code of the main parts of the
variable_properties_example.cu file.25 This code implements the 25
The code from initialization and ter-
mination hooks related to CUDA opera-
calculation of the property values per particle and per boundary tions is omitted, since it was described
triangle that the module must deliver to the Rocky solver. In turn, the in previous examples.

Rocky solver will use these values internally in the thermal model
calculations.

© 2022, esss - all rights reserved

 api : solver manual 77
ROCKY

1 #define ROCKY_CUDA_API
2

3 #include <rocky20/api/rocky_api.h>
4

6 struct MaterialData
7 {
8 double k_base_value;
9 double k_linear_coefficient;
10 };
11

12 struct GeometryData
13 {
14 double t_base_value;
15 double t_quadratic_coefficient;
16 };
17

18 struct ModuleData
19 {
20 MaterialData* m_data;
21 GeometryData* g_data;
22 bool enabled;
23 };

The code block above defines data structures for the module to
store the parameter values that users of the module entered via the
Rocky UI.

26 ROCKY_PLUGIN_CONFIGURE(input_data, data)
27 {
28 auto* module_data = new ModuleData();
29

30 int n_materials = input_data.get_number_materials();

31 module_data->m_data = new MaterialData[n_materials];
32

33 for (int i = 0; i < n_materials; ++i)

34 {
35 auto input_m_data = input_data.get_material_data(i);
36 module_data->m_data[i].k_base_value = input_m_data.get_double("k_base_value");
37 module_data->m_data[i].k_linear_coefficient = input_m_data.get_double("k_linear_coefficient");
38 }
39

40 int n_geometries = input_data.get_number_geometries();

41 module_data->g_data = new GeometryData[n_geometries];
42

43 for (int i = 0; i < n_geometries; ++i)

44 {
45 auto input_g_data = input_data.get_geometry_data(i);
46 module_data->g_data[i].t_base_value = input_g_data.get_double("t_base_value");
47 module_data->g_data[i].t_quadratic_coefficient = input_g_data.get_double("t_quadratic_coefficient");

© 2022, esss - all rights reserved

 api : solver manual 78
ROCKY

48 }
49

50 data = static_cast<void*>(module_data);
51 }
52

53

54 ROCKY_PLUGIN_SETUP(model, data)
55 {
56 auto* module_data = static_cast<ModuleData*>(data);
57

58 module_data->enabled = model.is_thermal_simulation();
59 }
60

61

62 ROCKY_PLUGIN_NON_DIMENSIONALIZE(model, data)
63 {
64 auto* module_data = static_cast<ModuleData*>(data);
65

66 if (!module_data->enabled) return;
67

68 double t_factor = model.get_temperature_factor();

69 double l_factor = model.get_length_factor();
70 double k_factor = model.get_energy_factor() / (model.get_time_factor() * l_factor * t_factor);
71

72 for (int i = 0; i < model.get_number_of_materials(); i++)

73 {
74 module_data->m_data[i].k_base_value /= k_factor;
75 module_data->m_data[i].k_linear_coefficient *= t_factor;
76 }
77

78 for (int i = 0; i < model.get_number_of_geometries(); i++)

79 {
80 module_data->g_data[i].t_base_value /= t_factor;
81 module_data->g_data[i].t_quadratic_coefficient *= l_factor * l_factor;
82 }
83 }

The code associated to the ROCKY_PLUGIN_CONFIGURE hook receives

the parameter values delivered by the Rocky UI, and then stores them
in the data structures previously defined. On the other hand, the
ROCKY_PLUGIN_SETUP hook is only used to verify if the project has the
thermal model enabled. The module will perform its operations
only if that is the case. Then the module parameters are non-
dimensionalized, in order to be used in the calculations that must be
made later on, during the simulation.
Since the module is intended to be used with static boundaries
only, it needs to prescribe the temperature of the boundary triangles
only once, during the initialization. In order to do that, the
ROCKY_PLUGIN_INITIALIZE_TRIANGLE hook is used in the following
way:

© 2022, esss - all rights reserved

 api : solver manual 79
ROCKY

86 ROCKY_PLUGIN_INITIALIZE_TRIANGLE(model, triangle, data)

87 {
88 auto* module_data = static_cast<ModuleData*>(data);
89

90 if (!module_data->enabled) return;
91

92 int geometry_index = triangle.get_geometry_index();

93 auto g_data = module_data->g_data[geometry_index];
94

95 double x = triangle.get_centroid().x;
96 double temperature = g_data.t_base_value * (1.0 + g_data.t_quadratic_coefficient * x * x );
97 triangle.set_temperature(temperature);
98 }

The code above applies equation (5.2) to the calculation of the

temperature of every boundary triangle in the simulation. If
the temperature distribution should be applied only to specific
boundaries, the code above must be modified in order to filter the
triangles belonging to those boundaries. Figure 5.7 shows an example
of the resulting temperature distribution in a specific case.

Figure 5.7: Example of the temperature

distribution on a boundary specified by
the module.

© 2022, esss - all rights reserved

 api : solver manual 80
ROCKY

Equation (5.1) specifies the thermal conductivity as a function of

the particle’s temperature. Since this temperature is updated at every
time iteration during the simulation, the module needs to update
the conductivity values at every iteration as well. That update must
be done within an iteration hook executed before the heat transfer
calculation, which are made right afterwards the contact forces
calculation. Therefore, the ROCKY PLUGIN PRE FORCE ON PARTICLES
hook is the most adequate for that task, as shown in the following
code block:

100 ROCKY_PLUGIN_PRE_FORCE_ON_PARTICLES(device_model, particle, data)

101 {
102 auto* module_data = static_cast<ModuleData*>(data);
103

104 if (!module_data->enabled) return;

105

106 int material_index = particle.get_material_index();

107 auto& m_data = module_data->m_data[material_index];
108 double temperature = particle.get_scalars().get_temperature();
109

110 double conductivity = m_data.k_base_value * (1.0 + m_data.k_linear_coefficient * temperature);

111 particle.set_thermal_conductivity(conductivity);
112 }
113 ROCKY_PLUGIN_PRE_FORCE_ON_PARTICLES_END()

This code calculates the thermal conductivity for all active particles
at a given time, according to equation (5.1). The conductivity value
just calculated is passed to the Rocky solver in the line 111 using the
set_thermal_conductivity method. The Rocky API : Solver includes
equivalent methods associated to particles, triangles and contacts, for
every property that can be overridden by a custom module.26 Figure 26
For a list of all those methods, please
refer to chapter 6 in this manual.
5.8 shows an example of a particle bed in which the particles’ thermal
conductivity has been calculated by the module described in this
section.
When a custom module that implements a variable property is
active in a simulation, Rocky will issue a warning message, indicating
which properties are being overridden by the module. Although the
constant property values being replaced will remain editable in the
Rocky UI, it is important to note that they will be ignored in all the
calculations done by the Rocky solver.

© 2022, esss - all rights reserved

 api : solver manual 81
ROCKY

Figure 5.8: Example of the variable ther-

mal conductivity on particles specified
by the module.

© 2022, esss - all rights reserved

ROCKY api : solver manual 82

6 Rocky API : Solver classes

6.1 IRockyAdhesiveDistanceData class reference

#include <rocky_timestep_api.h>

6.1.1 Public member functions

 void set_adhesive_distance (int home_index, int near_index, double adhesive_distance)

6.1.2 Detailed description

An IRockyAdhesiveDistanceData object provides data and utility methods needed

to estimate and set appropriate values of adhesive distance per material interaction.
The adhesive distance defines the upper limit for the activation of an adhesive
contact between two particles or between a particle and a geometry. An adhesive
contact only can exist when the effective gap distance between two entities is below
the adhesive distance value stipulated for the corresponding material interaction.
Therefore, no adhesive forces will be computed if that effective gap distance is larger
than the specified adhesive distance. If a custom module does not implement a
special adhesive distance calculation, Rocky will set the adhesive distances of all
material interactions to a fixed value equal to 1 mm.
The class IRockyAdhesiveDistanceData inherits all public methods of the class
IRockyInteractionCalculationsData.

6.1.3 Member function documentation

6.1.3.1 set_adhesive_distance()

void IRockyAdhesiveDistanceData::set_adhesive_distance ( int home_index, int near_index, double

adhesive_distance )

This method sets a value of the adhesive distance per material interaction, for a
custom adhesive force model.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 83

home_index The index of the first material.

near_index The index of the second material.
adhesive_distance The value of the adhesive distance just calculated.

6.2 IRockyInteractionCalculationsData class reference

#include <rocky_timestep_api.h>
Inherited by IRockyAdhesiveDistanceData, and IRockyTimestepData.

6.2.1 Public member functions

 int get_number_particle_groups () const
 int get_particle_material_index (int group_index) const
 double get_particle_min_sieve_size (int group_index) const
 double get_particle_max_sieve_size (int group_index) const
 double get_particle_min_mass (int group_index) const
 int get_number_geometry_materials () const
 int get_geometry_material_index (int index) const
 IRockyMaterial get_material (int index) const
 int get_material_interaction_index (int home_index, int near_index) const
 IRockyMaterialInteraction get_material_interaction (int home_index, int near_index) const

6.2.2 Detailed description

IRockyInteractionCalculationsData gives access to data and methods needed

for calculations related to materials, material interactions and particle groups,
during the setup phase of a module. IRockyInteractionCalculationsData is a
non-instantiable class, only derived classes can be used through Rocky API.

6.2.3 Member function documentation

6.2.3.1 get_geometry_material_index()

int IRockyInteractionCalculationsData::get_geometry_material_index ( int index ) const

Returns:
The internal index in Rocky that identifies a material.

Parameters:

index The index of a geometry material in a loop over all materials associated to geometries in
a project.

© 2022, esss - all rights reserved

ROCKY api : solver manual 84

6.2.3.2 get_material()

IRockyMaterial IRockyInteractionCalculationsData::get_material ( int index ) const

Returns:
An IRockyMaterial object that gives access to the property values associated to a given material.

Parameters:

index The internal index in Rocky that identifies a material.

6.2.3.3 get_material_interaction()

IRockyMaterialInteraction IRockyInteractionCalculationsData::get_material_interaction ( int

home_index, int near_index ) const

Returns:
An IRockyMaterialInteraction object that gives access to the property values associated to a given
material interaction.

Parameters:

index The internal index in Rocky that identifies a material interaction.

6.2.3.4 get_material_interaction_index()

int IRockyInteractionCalculationsData::get_material_interaction_index ( int home_index, int

near_index ) const

Returns:
The internal index in Rocky that identifies a material interaction.

Parameters:

home_index The index of the first material.

near_index The index of the second material.

6.2.3.5 get_number_geometry_materials()

int IRockyInteractionCalculationsData::get_number_geometry_materials ( ) const

Returns:
The total number of different materials associated to the geometries or boundaries in a project.

6.2.3.6 get_number_particle_groups()

int IRockyInteractionCalculationsData::get_number_particle_groups ( ) const

Returns:
The total number of particle groups defined in the project. A particle group is a category of particles
with the same shape and material.

© 2022, esss - all rights reserved

ROCKY api : solver manual 85

6.2.3.7 get_particle_material_index()

int IRockyInteractionCalculationsData::get_particle_material_index ( int group_index ) const

Returns:
The index that uniquely identifies internally in Rocky the material associated with a particle group.

Parameters:
group_index The index that identifies internally a particle group in Rocky.

6.2.3.8 get_particle_max_sieve_size()

double IRockyInteractionCalculationsData::get_particle_max_sieve_size ( int group_index ) const

Returns:
The sieve size of the largest particle in a particle group.

Parameters:
group_index The index that identifies internally a particle group in Rocky.

6.2.3.9 get_particle_min_mass()

double IRockyInteractionCalculationsData::get_particle_min_mass ( int group_index ) const

Returns:
The mass of the smallest particle in a particle group.

Parameters:
group_index The index that identifies internally a particle group in Rocky.

6.2.3.10 get_particle_min_sieve_size()

double IRockyInteractionCalculationsData::get_particle_min_sieve_size ( int group_index ) const

Returns:
The sieve size of the smallest particle in a particle group.

Parameters:
group_index The index that identifies internally a particle group in Rocky.

6.3 IRockyPluginData class reference

#include <rocky_plugin_data.h>

6.3.1 Public member functions

 IRockyPluginDataEntry get_model () const

© 2022, esss - all rights reserved

ROCKY api : solver manual 86

 bool has_material_interaction_data () const

 int get_number_material_interactions () const
 IRockyPluginDataEntry get_material_interaction_data (int index) const
 bool has_geometry_data () const
 int get_number_geometries () const
 IRockyPluginDataEntry get_geometry_data (int index) const
 bool has_particle_group_data () const
 int get_number_particle_groups () const
 IRockyPluginDataEntry get_particle_group_data (int index) const
 bool has_material_data () const
 int get_number_materials () const
 IRockyPluginDataEntry get_material_data (int index) const

6.3.2 Detailed description

IRockyPluginData gathers custom module data entered manually through the

Rocky UI. In order to appear on the Rocky UI, custom modules parameters must
be specified in the Python file that defines the components of the module. An
IRockyPluginData object is only available during the configuration step in ROCKY←-
_PLUGIN_CONFIGURE.

6.3.3 Member function documentation

6.3.3.1 get_geometry_data()

IRockyPluginDataEntry IRockyPluginData::get_geometry_data ( int index ) const

Returns:
An IRockyPluginDataEntry object that gives access to the values entered through the Rocky UI,
if they exist, for all parameters associated specifically to the module defined in the geometry
(boundaries) section.

Parameters:
index The index that uniquely identifies the specific geometry whose data must be retrieved.

6.3.3.2 get_material_data()

IRockyPluginDataEntry IRockyPluginData::get_material_data ( int index ) const

Returns:
An IRockyPluginDataEntry object that gives access to the values entered through the Rocky UI, if
they exist, for all parameters associated specifically to the module defined in the material section.

Parameters:
index The index that uniquely identifies the specific material whose data must be retrieved.

© 2022, esss - all rights reserved

ROCKY api : solver manual 87

6.3.3.3 get_material_interaction_data()

IRockyPluginDataEntry IRockyPluginData::get_material_interaction_data ( int index ) const

Returns:
An IRockyPluginDataEntry object that gives access to the values entered through the Rocky UI, if
they exist, for all parameters defined in the material interactions section of the module.

Parameters:

index The index that uniquely identifies the specific material interaction whose data must be
retrieved.

6.3.3.4 get_model()

IRockyPluginDataEntry IRockyPluginData::get_model ( ) const

Returns:
An IRockyPluginDataEntry object that gives access to the values entered through the Rocky UI for
all parameters in the model section of the module. These parameters are displayed in the [Data
Editors] panel when the module is selected in the data tree.

6.3.3.5 get_number_geometries()

int IRockyPluginData::get_number_geometries ( ) const

Returns:
The total number of geometries (boundaries) in the project.

6.3.3.6 get_number_material_interactions()

int IRockyPluginData::get_number_material_interactions ( ) const

Returns:
The total number of material interactions that it is possible to define with the current materials
defined in the Rocky project.

6.3.3.7 get_number_materials()

int IRockyPluginData::get_number_materials ( ) const

Returns:
The total number of materials defined in the project.

6.3.3.8 get_number_particle_groups()

int IRockyPluginData::get_number_particle_groups ( ) const

Returns:
The total number of particle groups defined in the project.

© 2022, esss - all rights reserved

ROCKY api : solver manual 88

6.3.3.9 get_particle_group_data()

IRockyPluginDataEntry IRockyPluginData::get_particle_group_data ( int index ) const

Returns:
An IRockyPluginDataEntry object that gives access to the values entered through the Rocky UI,
if they exist, for all parameters associated specifically to the module defined in the particle group
section.

Parameters:
index The index that uniquely identifies the specific particle group whose data must be
retrieved.

6.3.3.10 has_geometry_data()

bool IRockyPluginData::has_geometry_data ( ) const

Returns:
True if there is geometry data defined for the module, false otherwise.

6.3.3.11 has_material_data()

bool IRockyPluginData::has_material_data ( ) const

Returns:
True if there is any material property data defined for the module, false otherwise.

6.3.3.12 has_material_interaction_data()

bool IRockyPluginData::has_material_interaction_data ( ) const

Returns:
True if there is custom material interaction data defined for the module, false otherwise.

6.3.3.13 has_particle_group_data()

bool IRockyPluginData::has_particle_group_data ( ) const

Returns:
True if there is particle group data defined for the module, false otherwise.

6.4 IRockyPluginDataEntry class reference

#include <rocky_plugin_data.h>

6.4.1 Public member functions

 bool has (const char ∗_name) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 89

 bool get_bool (const char ∗_name) const

 int get_int (const char ∗_name) const
 double get_double (const char ∗_name) const
 std::string get_string (const char ∗_name) const
 int get_list_size (const char ∗_name) const
 IRockyPluginDataEntry get_list_item (const char ∗_name, int item_index) const

6.4.2 Detailed description

IRockyPluginDataEntry is a data unit corresponding to a single entity in Rocky (a

geometry, a material interaction, etc). It gives access to values of custom module
data entered manually through the Rocky UI. IRockyPluginDataEntry may contain
boolean, integer, double precision, and string data. Data arranged in lists of
IRockyPluginDataEntry is also allowed. The value of a parameter is retrieved
passing to the corresponding function the name string, as specified in the Python
file that defines the components of the module.

6.4.3 Member function documentation

6.4.3.1 get_bool()

bool IRockyPluginDataEntry::get_bool ( const char ∗ _name ) const

Returns:
The boolean value specified for the given parameter in the Rocky UI through a checkbox.

Parameters:
_name The name of the boolean parameter, as specified in the module definition Python file.

6.4.3.2 get_double()

double IRockyPluginDataEntry::get_double ( const char ∗ _name ) const

Returns:
The double precision value specified for the given parameter in the Rocky UI.

Parameters:
_name The name of the double precision parameter, as specified in the module definition
Python file.

6.4.3.3 get_int()

int IRockyPluginDataEntry::get_int ( const char ∗ _name ) const

Returns:
The integer value specified for the given parameter in the Rocky UI.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 90

_name The name of the integer parameter, as specified in the module definition Python file.

6.4.3.4 get_list_item()

IRockyPluginDataEntry IRockyPluginDataEntry::get_list_item ( const char ∗ _name, int item←-

_index ) const

Returns:
An IRockyPluginDataEntry object contained in the list.

Parameters:
_name The name of the list, as specified in the module definition Python file.

item_index The index that specifies the position in the list of the item to be retrieved.

6.4.3.5 get_list_size()

int IRockyPluginDataEntry::get_list_size ( const char ∗ _name ) const

Returns:
The number of IRockyPluginDataEntry objects that the list contains.

Parameters:
_name The name of the list, as specified in the module definition Python file.

6.4.3.6 get_string()

std::string IRockyPluginDataEntry::get_string ( const char ∗ _name ) const

Returns:
The string value specified for the given parameter in the Rocky UI.

Parameters:
_name The name of the string parameter, as specified in the module definition Python file.

6.4.3.7 has()

bool IRockyPluginDataEntry::has ( const char ∗ _name ) const

Returns:
True if the parameter specified by name actually exists in the IRockyPluginDataEntry object.
Otherwise, it returns false.

Parameters:
_name The name of the parameter, as specified in the module definition Python file

6.5 IRockyTimestepData class reference

#include <rocky_timestep_api.h>

© 2022, esss - all rights reserved

ROCKY api : solver manual 91

6.5.1 Public member functions

 int get_loading_n_steps () const

6.5.2 Detailed description

An IRockyTimestepData object provides the data and methods needed to estimate

a stable simulation timestep when a module implements a custom contact force
model. The class IRockyTimestepData inherits all public methods of the class
IRockyInteractionCalculationsData.

6.5.3 Member function documentation

6.5.3.1 get_loading_n_steps()

int IRockyTimestepData::get_loading_n_steps ( ) const

Returns:
The minimum number of timesteps that the loading period of the shortest collision in a simulation
can have. This is a parameter whose value is specified through the Rocky UI. An example of its
use can be seen in equation 5.1 of the DEM Technical Manual.

6.6 IRockyAdhesionOutputData struct reference

#include <rocky_contact_output_data_api.hpp>

6.6.1 Public member functions

 ROCKY_FUNCTIONS void set_normal_force (double value)
 ROCKY_FUNCTIONS void set_tangential_force (double3 value)

6.6.2 Detailed description

IRockyAdhesionOutputData is an interface to define some property values related

to an adhesive contact in a custom adhesion model. The values defined through
this interface include the normal and tangential components of the adhesion force.

6.6.3 Member function documentation

© 2022, esss - all rights reserved

ROCKY api : solver manual 92

6.6.3.1 set_normal_force()

ROCKY_FUNCTIONS void IRockyAdhesionOutputData::set_normal_force ( double value )

This method sets the value of the normal component of the adhesion force calculated
by a custom adhesion model. Rocky will sum this force to both entities associated to
the contact (two particles or a particle and a geometry triangle) using the appropriate
signs. Please note that since an adhesion force is attractive, normally it must be
defined with a negative sign (i.e. its orientation must be opposite to the normal
component of the contact force).

Parameters:

value The normal component of the adhesive force just calculated using a custom adhesion
model.

6.6.3.2 set_tangential_force()

ROCKY_FUNCTIONS void IRockyAdhesionOutputData::set_tangential_force ( double3 value )

This method can be used to set the value of the tangential component of the adhesion
force calculated by a custom adhesion model. Rocky will sum this force to both
entities associated to the contact (two particles or a particle and a geometry triangle)
using the appropriate signs. The use of this function is optional, since only in
specific cases (like in a liquid bridge model) an adhesion model will need to specify
a tangential force component.

Parameters:

value The tangential component of the adhesive force expressed in Cartesian coordinates.

6.7 IRockyBreakableParticle struct reference

#include <rocky_particle_api.hpp>

6.7.1 Public member functions

 double get_minimum_fragment_size () const
 double get_original_volume () const
 int get_particle_group_index () const
 double get_strength () const
 double get_original_size () const
 void set_as_unbreakable () const
 IRockyParticleScalars get_scalars ()
 IRockyParticleBreakageScalars get_breakage_scalars ()

© 2022, esss - all rights reserved

ROCKY api : solver manual 93

6.7.2 Detailed description

IRockyBreakableParticle is an interface for particles enabled to break through

instantaneous breakage during a simulation. It may used for the initialization
of IRockyParticleBreakageScalars that custom instantaneous breakage and/or
fragment size distribution models may need.

6.7.3 Member function documentation

6.7.3.1 get_breakage_scalars()

IRockyParticleBreakageScalars IRockyBreakableParticle::get_breakage_scalars ( )

Returns:
An IRockyParticleBreakageScalars object, that gives access to all particle breakage scalars
variables defined in the project.

6.7.3.2 get_minimum_fragment_size()

double IRockyBreakableParticle::get_minimum_fragment_size ( ) const

Returns:
The minimum size that a fragment generated at a breakage event of the particle can have. Please
refer to section 2.4.3 of the DEM Technical Manual for more information about how this parameter
is defined.

6.7.3.3 get_original_size()

double IRockyBreakableParticle::get_original_size ( ) const

Returns:
The value of the particle's size at the moment it enters a simulation.

6.7.3.4 get_original_volume()

double IRockyBreakableParticle::get_original_volume ( ) const

Returns:
The volume of the particle at the moment it enters a simulation.

6.7.3.5 get_particle_group_index()

int IRockyBreakableParticle::get_particle_group_index ( ) const

Returns:
The index that identifies internally the particle group to which the particle belongs.

© 2022, esss - all rights reserved

ROCKY api : solver manual 94

6.7.3.6 get_scalars()

IRockyParticleScalars IRockyBreakableParticle::get_scalars ( )

Returns:
An IRockyParticleScalars object, that gives access to all particle scalars variables defined in the
project.

6.7.3.7 get_strength()

double IRockyBreakableParticle::get_strength ( ) const

Returns:
A random value between 0 and 1 assigned to a particle at the time of generation. This value can be
related to the breakage probability in a custom instantaneous breakage model.

6.7.3.8 set_as_unbreakable()

void IRockyBreakableParticle::set_as_unbreakable ( ) const

If this method is called during breakage initialization, the particle will be marked to
be ignored at all instantaneous breakage-related procedures during the simulation.

6.8 IRockyContact struct reference

#include <rocky_contact_api.hpp>

6.8.1 Public member functions

 ROCKY_FUNCTIONS IRockyMaterial get_home_material () const
 ROCKY_FUNCTIONS IRockyMaterial get_near_material () const
 ROCKY_FUNCTIONS IRockyMaterialInteraction get_material_interaction () const
 ROCKY_FUNCTIONS int get_material_interaction_index () const
 ROCKY_FUNCTIONS IRockyParticle get_home_particle () const
 ROCKY_FUNCTIONS IRockyParticle get_near_particle () const
 ROCKY_FUNCTIONS IRockyGeometryTriangle get_near_triangle () const
 ROCKY_FUNCTIONS int get_near_geometry_index () const
 ROCKY_FUNCTIONS bool is_particle_particle_contact () const
 ROCKY_FUNCTIONS bool is_particle_triangle_contact () const
 ROCKY_FUNCTIONS double get_previous_overlap () const
 ROCKY_FUNCTIONS double get_overlap () const
 ROCKY_FUNCTIONS double3 get_normal_unit_vector () const
 ROCKY_FUNCTIONS double3 get_contact_position () const

© 2022, esss - all rights reserved

ROCKY api : solver manual 95

 ROCKY_FUNCTIONS bool just_started_frictional () const

 ROCKY_FUNCTIONS bool just_started_adhesive () const
 ROCKY_FUNCTIONS bool is_loading () const
 ROCKY_FUNCTIONS bool is_unloading () const
 ROCKY_FUNCTIONS bool is_positive_oriented () const
 ROCKY_FUNCTIONS double get_current_time () const
 ROCKY_FUNCTIONS double get_timestep () const
 ROCKY_FUNCTIONS IRockyContactScalars get_particle_contact_scalars () const
 ROCKY_FUNCTIONS IRockyContactScalars get_triangle_contact_scalars () const
 ROCKY_FUNCTIONS double get_home_stiffness () const
 ROCKY_FUNCTIONS double get_near_stiffness () const
 ROCKY_FUNCTIONS double get_equivalent_stiffness () const
 ROCKY_FUNCTIONS double get_reduced_young_modulus () const
 ROCKY_FUNCTIONS double get_equivalent_mass () const
 ROCKY_FUNCTIONS double get_equivalent_radius () const
 ROCKY_FUNCTIONS double get_normal_contact_force () const
 ROCKY_FUNCTIONS double3 get_tangential_contact_force () const
 ROCKY_FUNCTIONS double3 calculate_relative_velocity () const
 ROCKY_FUNCTIONS double get_restitution_coefficient () const
 ROCKY_FUNCTIONS void set_restitution_coefficient (double value)
 ROCKY_FUNCTIONS double get_dynamic_friction_coefficient () const
 ROCKY_FUNCTIONS void set_dynamic_friction_coefficient (double value)
 ROCKY_FUNCTIONS double get_static_friction_coefficient () const
 ROCKY_FUNCTIONS void set_static_friction_coefficient (double value)
 ROCKY_FUNCTIONS double get_sliding_distance () const
 ROCKY_FUNCTIONS bool get_is_sliding_marker () const
 ROCKY_FUNCTIONS double get_normal_relative_velocity () const
 ROCKY_FUNCTIONS double3 get_tangential_relative_velocity () const
 ROCKY_FUNCTIONS double get_normal_adhesion_force () const
 ROCKY_FUNCTIONS double3 get_tangential_adhesion_force () const
 ROCKY_FUNCTIONS double3 get_previous_normal_vector () const
 ROCKY_FUNCTIONS double3 get_previous_moment_vector () const
 ROCKY_FUNCTIONS void set_previous_moment_vector (double3 value)

6.8.2 Detailed description

IRockyContact is an interface for the internal contact object in Rocky. A contact

object is the code representation of the relationship between two particles or between
a particle and a geometry triangle that have a force interaction at a given time. In
the first case, it will be a particle-to-particle contact (sometimes abbreviated to particle-
contact), whereas in the latter case, it will be a particle-to-triangle contact (sometimes
abbreviated to triangle-contact).

© 2022, esss - all rights reserved

ROCKY api : solver manual 96

A contact in which there exists an actual overlap between the entities is referred
to as a frictional contact. If an adhesive model is active, an adhesive force might exist
even if the entities are not physically touching each other. In that case, an adhesive
contact will be established between those entities.
In a particle-to-particle contact, one of the particles is identified as home particle,
whereas the other is identified as near particle. There is no special rule for labeling
particles in this type of contacts, any of the two particles can be labeled as home or
near. On the other hand, in a particle-to-triangle contact, the particle is always
referred to as home particle, while the triangle is referred to as near triangle.
Whenever it is necessary to distinguish between two contacting entities, the prefixes
home and near are used in the associated method names. The normal unit vector
associated to a contact is always constructed pointing to the home particle.
Contact scalars are special variables that store values per contact that are
preserved between time iterations. The preservation of those values is guaranteed
during the whole lifetime of a contact. Internally, contact scalars are stored
separately for particle-to-particle contacts and for particle-to-triangle contacts. In
order to differentiate them, the former are named particle contact scalars, whereas
the latter are named triangle contact scalars

6.8.3 Member function documentation

6.8.3.1 calculate_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyContact::calculate_relative_velocity ( ) const

This method will calculate the relative velocity vector at the contact point. This
relative velocity is defined as the difference between the velocities of points located at
the home particle and the near particle or geometry, both coincident instantaneously
with the contact point.

Attention:
Since this calculation can be costly, modules that need values of this relative velocity may alterna-
tively enable the storage of its normal and tangential components. These components are calculated
internally by Rocky during the contact force calculation stage, but discarded afterwards. How-
ever, by using the IRockyContactScalarsModel::enable_storage_normal_relative_velocity
and IRockyContactScalarsModel::enable_storage_tangential_relative_velocity methods, a
module can activate the storage of those components in order to make them available at any point
during a time iteration.

Returns:
The current relative velocity vector between two contacting particles or a particle and a geometry,
at the contact point.

© 2022, esss - all rights reserved

ROCKY api : solver manual 97

6.8.3.2 get_contact_position()

ROCKY_FUNCTIONS double3 IRockyContact::get_contact_position ( ) const

Returns:
The Cartesian coordinates of the point at which the contact force is applied.

6.8.3.3 get_current_time()

ROCKY_FUNCTIONS double IRockyContact::get_current_time ( ) const

Returns:
The current simulation time.

6.8.3.4 get_dynamic_friction_coefficient()

ROCKY_FUNCTIONS double IRockyContact::get_dynamic_friction_coefficient ( ) const

Returns:
The value of the coefficient of dynamic or kinetic friction associated to the contact. If this coefficient
is defined as a variable property and its value is specified by a custom module, this method will
return that value. Otherwise, it will return the value set through the Rocky UI for the corresponding
material interaction.

6.8.3.5 get_equivalent_mass()

ROCKY_FUNCTIONS double IRockyContact::get_equivalent_mass ( ) const

Returns:
The value of the equivalent or effective mass for the contact, as defined in equation 2.10 of the DEM
Technical Manual.

6.8.3.6 get_equivalent_radius()

ROCKY_FUNCTIONS double IRockyContact::get_equivalent_radius ( ) const

Returns:
The value of the equivalent or effective radius for the contact, as defined in equation 2.15 of the
DEM Technical Manual.

6.8.3.7 get_equivalent_stiffness()

ROCKY_FUNCTIONS double IRockyContact::get_equivalent_stiffness ( ) const

Returns:
The value of the equivalent stiffness for the contact, calculated as in equation 2.3 of the DEM
Technical Manual. The returned value is already multiplied by the numerical softening factor,
which is commonly used as a practical way of increasing the simulation timestep. For more details,
please refer to section 5.2.4 of the DEM Technical Manual.

© 2022, esss - all rights reserved

ROCKY api : solver manual 98

6.8.3.8 get_home_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyContact::get_home_material ( ) const

Returns:
An IRockyMaterial object that gives access to the values of physical properties associated to the
material from which particle labeled as home is made.

6.8.3.9 get_home_particle()

ROCKY_FUNCTIONS IRockyParticle IRockyContact::get_home_particle ( ) const

Returns:
An IRockyParticle object representing the home particle. This object gives access to several
instantaneous properties associated to that particle.

6.8.3.10 get_home_stiffness()

ROCKY_FUNCTIONS double IRockyContact::get_home_stiffness ( ) const

Returns:
The value of the stiffness associated to the home particle, calculated as in equation 2.5 of the DEM
Technical Manual. The returned value is already multiplied by the numerical softening factor,
which is commonly used as a practical way of increasing the simulation timestep. For more details,
please refer to section 5.2.4 of the DEM Technical Manual.

6.8.3.11 get_is_sliding_marker()

ROCKY_FUNCTIONS bool IRockyContact::get_is_sliding_marker ( ) const

Returns:
The value of the sliding marker registered during the most recent calculation of the tangential
component of the contact force. This value will be available only if its storage was enabled by using
the IRockyContactScalarsModel::enable_storage_is_sliding_marker method. A segmentation
fault will occur otherwise.

6.8.3.12 get_material_interaction()

ROCKY_FUNCTIONS IRockyMaterialInteraction IRockyContact::get_material_interaction ( ) const

Returns:
An IRockyMaterialInteraction object that gives access to the values of physical properties
associated to the material interaction that corresponds to the contact.

6.8.3.13 get_material_interaction_index()

ROCKY_FUNCTIONS int IRockyContact::get_material_interaction_index ( ) const

Returns:
The internal index of the material interaction associated to the contact. Every pair of materials
defined in a project has a unique index associated to it. Both built-in and custom material
interactions are stored internally using the same indexes.

© 2022, esss - all rights reserved

ROCKY api : solver manual 99

6.8.3.14 get_near_geometry_index()

ROCKY_FUNCTIONS int IRockyContact::get_near_geometry_index ( ) const

Returns:
The internal index that uniquely identifies the geometry to which belongs the geometry triangle in
a particle-to-triangle contact.

6.8.3.15 get_near_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyContact::get_near_material ( ) const

Returns:
An IRockyMaterial object that gives access to the values of physical properties associated to the
material from which the near particle or triangle is made.

6.8.3.16 get_near_particle()

ROCKY_FUNCTIONS IRockyParticle IRockyContact::get_near_particle ( ) const

Returns:
An IRockyParticle object representing the near particle in a particle-to-triangle contact. This object
gives access to several instantaneous properties associated to that particle.

6.8.3.17 get_near_stiffness()

ROCKY_FUNCTIONS double IRockyContact::get_near_stiffness ( ) const

Returns:
The value of the stiffness associated to the near particle or the near triangle, depending on the
contact type. In the former case, the stiffness is calculated with equation 2.5, whereas the equation
2.6 is applied in the latter case, both equations in the DEM Technical Manual. The returned value
is already multiplied by the numerical softening factor, which is commonly used as a practical way
of increasing the simulation timestep. For more details, please refer to section 5.2.4 of the DEM
Technical Manual.

6.8.3.18 get_near_triangle()

ROCKY_FUNCTIONS IRockyGeometryTriangle IRockyContact::get_near_triangle ( ) const

Returns:
An IRockyGeometryTriangle object representing the near geometry triangle in a particle-to-triangle
contact. This object gives access to some geometric properties associated to that triangle.

6.8.3.19 get_normal_adhesion_force()

ROCKY_FUNCTIONS double IRockyContact::get_normal_adhesion_force ( ) const

Returns:
The value of the normal component of the adhesion force calculated during the last adhesion force
calculation stage executed. This value will be available only if its storage was enabled by using the
IRockyContactScalarsModel::enable_storage_normal_adhesion_force method. A segmentation
fault will occur otherwise.

© 2022, esss - all rights reserved

ROCKY api : solver manual 100

6.8.3.20 get_normal_contact_force()

ROCKY_FUNCTIONS double IRockyContact::get_normal_contact_force ( ) const

Returns:
The value of the normal component of the contact force, calculated according to the active normal
contact force model. Depending on the point from where this function is called, a different
force value can be returned. If called from ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS, the returned
value will correspond to the normal force component calculated during the previous timestep.
On the other hand, if called from ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS, the value will be the
recently calculated normal force component for the current timestep. Moreover, this function is not
supposed to be called from ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS, since this hook is meant to
be used to calculate and set the normal force component for the contact.

6.8.3.21 get_normal_relative_velocity()

ROCKY_FUNCTIONS double IRockyContact::get_normal_relative_velocity ( ) const

Returns:
The value of the normal component of the contact's relative velocity calculated during the last
contact force calculation stage executed. This value will be available only if its storage was enabled
by using the IRockyContactScalarsModel::enable_storage_normal_relative_velocity method.
A segmentation fault will occur otherwise.

6.8.3.22 get_normal_unit_vector()

ROCKY_FUNCTIONS double3 IRockyContact::get_normal_unit_vector ( ) const

Returns:
The unit normal vector in Cartesian coordinates. Conventionally, this vector is oriented always
pointing to the home particle.

6.8.3.23 get_overlap()

ROCKY_FUNCTIONS double IRockyContact::get_overlap ( ) const

Returns:
The value of the current overlap, which is the small distance that a particle overlaps with another
particle or a boundary, measured in the normal direction. In contact models, it is taken as a
measurement of the total deformation of the contacting entities at any given time during a collision.
Therefore, it is usually the main input parameter for calculating the normal contact force. For
adhesive contacts in which physical contact has not been reached yet, this function will return a
negative value. In this case, the absolute value of the overlap can be interpreted as the gap between
the interacting entities, measured in the direction defined by the normal unit vector. It is common
for adhesive forces to be functions of this gap distance.

6.8.3.24 get_particle_contact_scalars()

ROCKY_FUNCTIONS IRockyContactScalars IRockyContact::get_particle_contact_scalars ( ) const

Returns:
An IRockyContactScalars object that gives access to all particle-to-particle contact scalars defined
in the project.

© 2022, esss - all rights reserved

ROCKY api : solver manual 101

6.8.3.25 get_previous_moment_vector()

ROCKY_FUNCTIONS double3 IRockyContact::get_previous_moment_vector ( ) const

Returns:
The value the previous rolling resistance moment stored by a custom module that implements
a custom rolling resistance model. This moment will be available only if a corresponding
scalar was enabled by using the IRockyContactScalarsModel::enable_previous_moment_vector
method and the module explicitly stored its value in the previous iteration, by using the
IRockyContact::set_previous_moment_vector method.

6.8.3.26 get_previous_normal_vector()

ROCKY_FUNCTIONS double3 IRockyContact::get_previous_normal_vector ( ) const

Returns:
The value of the contact's normal unit vector recorded during the previous time itera-
tion. This value will be available only if its automatic storage was enabled by using the
IRockyContactScalarsModel::enable_storage_previous_normal_vector method. A segmenta-
tion fault will occur otherwise.

6.8.3.27 get_previous_overlap()

ROCKY_FUNCTIONS double IRockyContact::get_previous_overlap ( ) const

Returns:
The value of the overlap corresponding to the previous timestep.

6.8.3.28 get_reduced_young_modulus()

ROCKY_FUNCTIONS double IRockyContact::get_reduced_young_modulus ( ) const

Returns:
The value of the reduced Young's modulus as defined in equation 2.14 of the DEM Technical
Manual. This property is usually used in the Hertzian contact model and models derived from it.
The returned value is already multiplied by the numerical softening factor, which is commonly
used as a practical way of increasing the simulation timestep. For more details, please refer to
section 5.2.4 of the DEM Technical Manual.

6.8.3.29 get_restitution_coefficient()

ROCKY_FUNCTIONS double IRockyContact::get_restitution_coefficient ( ) const

Returns:
The value of the coefficient of restitution associated to the contact. If the restitution coefficient is a
variable property specified by a custom module, this method will return that value. Otherwise, it
will return the value set through the Rocky UI for the corresponding material interaction.

6.8.3.30 get_sliding_distance()

ROCKY_FUNCTIONS double IRockyContact::get_sliding_distance ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 102

Returns:
The value of the sliding distance calculated during the most recent simulation timestep. The
value of this distance will be available only if its storage was enabled during the setup of the
module by using the IRockyContactScalarsModel::enable_storage_sliding_distance method.
A segmentation fault will occur otherwise.

6.8.3.31 get_static_friction_coefficient()

ROCKY_FUNCTIONS double IRockyContact::get_static_friction_coefficient ( ) const

Returns:
The value of the coefficient of static friction associated to the contact. If this coefficient is defined
as a variable property and its value is specified by a custom module, this method will return that
value. Otherwise, it will return the value set through the Rocky UI for the corresponding material
interaction.

6.8.3.32 get_tangential_adhesion_force()

ROCKY_FUNCTIONS double3 IRockyContact::get_tangential_adhesion_force ( ) const

Returns:
The value of the tangential component of the adhesion force calculated during the last adhesion
force calculation stage executed. This value will be available only if its storage was enabled by
using the IRockyContactScalarsModel::enable_storage_tangential_adhesion_force method. A
segmentation fault will occur otherwise.

6.8.3.33 get_tangential_contact_force()

ROCKY_FUNCTIONS double3 IRockyContact::get_tangential_contact_force ( ) const

Returns:
The tangential component of the contact force as a vector in Cartesian coordinates, calculated
according to the active tangential contact force model. Conventionally, the returned tangential force
is the one whose orientation coincides with the tangential force acting on the home particle.
If called from ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS, the returned value will correspond to the
tangential force component calculated during the previous timestep. On the other hand, if
called from ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS or from other hooks executed after that point,
the value will be the recently calculated tangential force component for the current timestep.
Moreover, this function is not supposed to be called from ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_←-
CONTACTS, since this hook is meant to be used to calculate and set the tangential force component
for the contact. For tangential force models other than the Linear Spring Coulomb Limit and
Mindlin-Deresiewicz models, the storage of this force must be enabled explicitly by using the
IRockyContactScalarsModel::enable_storage_tangential_contact_force method.

6.8.3.34 get_tangential_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyContact::get_tangential_relative_velocity ( ) const

Returns:
The value of the tangential component of the contact's relative velocity calculated during the last con-
tact force calculation stage executed. This value will be available only if its storage was enabled by
using the IRockyContactScalarsModel::enable_storage_tangential_relative_velocity method.
A segmentation fault will occur otherwise.

© 2022, esss - all rights reserved

ROCKY api : solver manual 103

6.8.3.35 get_timestep()

ROCKY_FUNCTIONS double IRockyContact::get_timestep ( ) const

Returns:
The magnitude of the simulation timestep.

6.8.3.36 get_triangle_contact_scalars()

ROCKY_FUNCTIONS IRockyContactScalars IRockyContact::get_triangle_contact_scalars ( ) const

Returns:
An IRockyContactScalars object that gives access to all particle-to-triangle contact scalars defined
in the project.

6.8.3.37 is_loading()

ROCKY_FUNCTIONS bool IRockyContact::is_loading ( ) const

Returns:
True if the contact is in a loading period (overlap increasing), false otherwise.

6.8.3.38 is_particle_particle_contact()

ROCKY_FUNCTIONS bool IRockyContact::is_particle_particle_contact ( ) const

Returns:
True if the contact is a particle-to-particle contact, false otherwise.

6.8.3.39 is_particle_triangle_contact()

ROCKY_FUNCTIONS bool IRockyContact::is_particle_triangle_contact ( ) const

Returns:
True if the contact is a particle-to-triangle contact, false otherwise.

6.8.3.40 is_positive_oriented()

ROCKY_FUNCTIONS bool IRockyContact::is_positive_oriented ( ) const

Returns:
True if the topological orientation of the contact coincides with the conventional positive orientation.

6.8.3.41 is_unloading()

ROCKY_FUNCTIONS bool IRockyContact::is_unloading ( ) const

Returns:
True if the contact is in a unloading period (overlap decreasing), false otherwise.

© 2022, esss - all rights reserved

ROCKY api : solver manual 104

6.8.3.42 just_started_adhesive()

ROCKY_FUNCTIONS bool IRockyContact::just_started_adhesive ( ) const

Returns:
True if the contact is adhesive and it has begun at the current timestep, false otherwise.

6.8.3.43 just_started_frictional()

ROCKY_FUNCTIONS bool IRockyContact::just_started_frictional ( ) const

Returns:
True if the contact is frictional and it has begun at the current timestep, false otherwise.

6.8.3.44 set_dynamic_friction_coefficient()

ROCKY_FUNCTIONS void IRockyContact::set_dynamic_friction_coefficient ( double value )

This method sets the value of the coefficient of dynamic friction at a frictional
contact. It can be used only if that coefficient was defined as a variable property
in the module's specification file. It is important to note that the value of this
coefficient must be set at the beginning of a contact, before the stage of contact
forces calculation. Otherwise, the value set by this method will not be used in that
calculation, causing undefined behavior in the collisions.

Parameters:
value The value of the coefficient of dynamic friction that must be used in the contact.

6.8.3.45 set_previous_moment_vector()

ROCKY_FUNCTIONS void IRockyContact::set_previous_moment_vector ( double3 value )

This method allows a module implementing a custom rolling resistance model to

store the value of the rolling resistance moment for availability in the next time
iteration. It can be used only if the corresponding contact scalar was enabled by
using the IRockyContactScalarsModel::enable_previous_moment_vector method.
The difference of the contact scalar that stores this moment in relation to a regular
contact scalar is that the orientation of the stored vector is always preserved,
regardless of possible internal changes in the topology of the contact.

Parameters:
value The value of the rolling resistance moment just calculated.

6.8.3.46 set_restitution_coefficient()

ROCKY_FUNCTIONS void IRockyContact::set_restitution_coefficient ( double value )

© 2022, esss - all rights reserved

ROCKY api : solver manual 105

This method sets the value of the coefficient of restitution for a collision. It can be
used only if the coefficient of restitution was defined as a variable property in the
module's specification file. It is important to note that the value of the restitution
coefficient must be set at the beginning of a contact, before the stage of contact
forces calculation. Otherwise, the value set by this method will not be used in that
calculation, causing unphysical behavior in the collisions.

Parameters:

value The value of the coefficient of restitution that must be used in the contact.

6.8.3.47 set_static_friction_coefficient()

ROCKY_FUNCTIONS void IRockyContact::set_static_friction_coefficient ( double value )

This method sets the value of the coefficient of static friction at a frictional contact. It
can be used only if that coefficient was defined as a variable property in the module's
specification file. It is important to note that the value of this coefficient must be
set at the beginning of a contact, before the stage of contact forces calculation.
Otherwise, the value set by this method will not be used in that calculation, causing
unphysical behavior in the collisions.

Parameters:

value The value of the coefficient of static friction that must be used in the contact.

6.9 IRockyContactIntermediateData struct reference

#include <rocky_contact_intermediate_data_api.hpp>

6.9.1 Public member functions

 ROCKY_FUNCTIONS double3 get_home_centroid_to_contact_point_vector () const
 ROCKY_FUNCTIONS double3 get_near_centroid_to_contact_point_vector () const
 ROCKY_FUNCTIONS double get_friction_coefficient () const

6.9.2 Detailed description

IRockyContactIntermediateData is an interface to access some useful property

values related to the contact that can be needed during the calculation steps of a
custom contact model, i.e. calculation of the normal and tangential forces, and
calculation of the impact energy.

© 2022, esss - all rights reserved

ROCKY api : solver manual 106

6.9.3 Member function documentation

6.9.3.1 get_friction_coefficient()

ROCKY_FUNCTIONS double IRockyContactIntermediateData::get_friction_coefficient ( ) const

Returns:
The coefficient of friction, which is the ratio of the frictional force resisting the motion of the
two surfaces in contact to the normal force pressing the two surfaces together. The coefficient of
friction is equal to the dynamic or static friction coefficient defined for the corresponding material
interaction, depending on the existence or not of sliding at the contact. Since the sliding condition
must be specified by a module in ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS, this method
must be called after that hook. If called before that point, the returned value is undetermined.

6.9.3.2 get_home_centroid_to_contact_point_vector()

ROCKY_FUNCTIONS double3 IRockyContactIntermediateData::get_home_centroid_to_contact_point←-

_vector ( ) const

Returns:
Cartesian coordinates of the vector that joins the home particle centroid to the contact point.

6.9.3.3 get_near_centroid_to_contact_point_vector()

ROCKY_FUNCTIONS double3 IRockyContactIntermediateData::get_near_centroid_to_contact_point←-

_vector ( ) const

Returns:
Cartesian coordinates of the vector that joins the near particle centroid to the contact point. If the
near entity is a triangle instead of a particle, a zero vector will be returned.

6.10 IRockyContactOutputData struct reference

#include <rocky_contact_output_data_api.hpp>

6.10.1 Public member functions

 ROCKY_FUNCTIONS void set_normal_force (double value)
 ROCKY_FUNCTIONS void set_tangential_force (double3 value)
 ROCKY_FUNCTIONS void set_home_impact_energy (double value)
 ROCKY_FUNCTIONS void set_near_impact_energy (double value)
 ROCKY_FUNCTIONS void set_sliding (bool value)
 ROCKY_FUNCTIONS void set_home_moment (double3 value)
 ROCKY_FUNCTIONS void set_near_moment (double3 value)
 ROCKY_FUNCTIONS void set_rolling_dissipated_power (double value)
 ROCKY_FUNCTIONS double get_normal_force ()
 ROCKY_FUNCTIONS double3 get_tangential_force ()
 ROCKY_FUNCTIONS double get_normal_relative_velocity ()
 ROCKY_FUNCTIONS double3 get_tangential_relative_velocity ()

© 2022, esss - all rights reserved

ROCKY api : solver manual 107

6.10.2 Detailed description

IRockyContactOutputData is an interface to define some property values related to

a contact, which are needed during the calculation steps of a custom contact model.
The values defined through this interface can include normal and tangential forces,
and impact energy.
Each set method present in this interface is intended to be used at a different
calculation step of the contact model:

 Normal contact force calculation within the code associated to the

ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS hook:

♦ IRockyContactOutputData::set_normal_force

 Tangential contact force calculation within the code associated to the

ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS hook:

♦ IRockyContactOutputData::set_tangential_force
♦ IRockyContactOutputData::set_sliding

 Impact energy calculation within the code associated to the

ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS hook:

♦ IRockyContactOutputData::set_home_impact_energy
♦ IRockyContactOutputData::set_near_impact_energy

It is mandatory that the values of the properties above be defined in the respective
method. If not defined, the behavior of the particles during the simulation can
become indeterminate. Please refer to the individual methods' documentation for
further details about each of them.

6.10.3 Member function documentation

6.10.3.1 get_normal_force()

ROCKY_FUNCTIONS double IRockyContactOutputData::get_normal_force ( )

Returns:
The normal component of the contact force calculated during the current iteration. This method
is intended to be called after the normal force is calculated from the contact model pipeline
(ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS in a custom implementation). If called before the
moment when the normal force is set for the current contact in the current iteration, the value
returned is undetermined.

Attention:

© 2022, esss - all rights reserved

ROCKY api : solver manual 108

Note that the value returned by this method may differ from the value returned by
IRockyContact::get_normal_contact_force, as the latter returns the current normal force value
in memory, which is usually zero (for new contacts) or the value calculated in the last normal force
step for this contact.

6.10.3.2 get_normal_relative_velocity()

ROCKY_FUNCTIONS double IRockyContactOutputData::get_normal_relative_velocity ( )

Returns:
The normal component of the relative velocity at the contact point. This relative velocity is defined
as the difference between the absolute velocities of points on the home particle and the near particle
or boundary that instantaneously coincide with the contact point.

6.10.3.3 get_tangential_force()

ROCKY_FUNCTIONS double3 IRockyContactOutputData::get_tangential_force ( )

Returns:
The tangential component of the contact force calculated at the current iteration as a vector in
Cartesian coordinates. This method is intended to be called after the tangential force calculation
step from the contact model pipeline (ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS in a custom
implementation). If called before the moment when the tangential force is set for the current
contact in the current iteration, the value returned is undetermined.

Attention:
Note that the value returned from this method may differ from the value returned by
IRockyContact::get_tangential_contact_force, as the latter returns the current tangential force
vector in memory, which is usually zero (for new contacts) or the value calculated in the last
tangential force step for this contact.

6.10.3.4 get_tangential_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyContactOutputData::get_tangential_relative_velocity ( )

Returns:
The tangential component of the relative velocity at the contact point. This relative velocity is
defined as the difference between the absolute velocities of points on the home particle and the
near particle or boundary that instantaneously coincide with the contact point.

6.10.3.5 set_home_impact_energy()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_home_impact_energy ( double value )

This method must be used if users want to specify an impact energy obtained by
means of a special calculation scheme, different from the one defined by equation
4.10 of the DEM Technical Manual. The impact energy value specified by this
method for the home particle will be used in Rocky for processing instantaneous
breakage, energy spectra and collision statistics. In the specific case of instantaneous

© 2022, esss - all rights reserved

ROCKY api : solver manual 109

breakage, Rocky will sum the impact energies from all contacts associated to a
particle in order to quantify the damage on the particle. This method is intended
to be called from ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS, since this hook is the
one designed for calculating and setting the impact energy values. Using it outside
this hook can lead to undefined behavior.

Parameters:
value The impact energy for the home particle just calculated using a custom model.

6.10.3.6 set_home_moment()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_home_moment ( double3 value )

This method sets the value of the rolling resistance moment that must be applied
to the particle labeled as home particle at a contact. This method is intended
to be called from ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS, as this hook
is designed specifically to be used by a module implementing a custom rolling
resistance model, to calculate and set the rolling resistance moments acting on the
particles at a contact. Using this method outside that hook can lead to undefined
behavior.

Parameters:
value The rolling resistance moment vector acting over the home particle.

6.10.3.7 set_near_impact_energy()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_near_impact_energy ( double value )

This method must be used if users want to specify an impact energy obtained by
means of a special calculation scheme, different from the one defined by equation
4.10 of the DEM Technical Manual. The impact energy value specified by this
method for the near particle will be used in Rocky for processing instantaneous
breakage, energy spectra and collision statistics. In the specific case of instantaneous
breakage, Rocky will sum the impact energies from all contacts associated to a
particle in order to quantify the damage on the particle. This method is intended
to be called from ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS, since this hook is the
one designed for calculating and setting the impact energy values. Using it outside
this hook can lead to undefined behavior.

Parameters:
value The impact energy for the near particle just calculated using a custom model.

6.10.3.8 set_near_moment()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_near_moment ( double3 value )

© 2022, esss - all rights reserved

ROCKY api : solver manual 110

This method sets the value of the rolling resistance moment that must be applied
to the particle labeled as near particle at a particle-to-particle contact. This method
is intended to be called from ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS, as
this hook is designed specifically to be used by a module implementing a custom
rolling resistance model, to calculate and set the rolling resistance moments acting
on the particles at a contact. Using this method outside that hook can lead to
undefined behavior.

Parameters:
value The rolling resistance moment vector acting over the near particle.

6.10.3.9 set_normal_force()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_normal_force ( double value )

This method sets the value of the normal component of the contact force calculated
by a custom contact model. Rocky will sum this force to both entities associated to
the contact (two particles or a particle and a geometry triangle) using the appropriate
signs. This method is intended to be called from ROCKY_PLUGIN_NORMAL_FORCE_←-
ON_CONTACTS, since this hook is meant to be used to calculate and set the normal
force component for the contact. Using it outside this hook can lead to undefined
behavior.

Parameters:
value The normal component of the contact force just calculated using a custom model.

6.10.3.10 set_rolling_dissipated_power()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_rolling_dissipated_power ( double value )

This method sets the value of the instantaneous power dissipated at a contact, due to
the action of the rolling resistance moments calculated by a custom rolling resistance
model. The value of this power will be used exclusively by collision statistics and
energy spectra modules, if they are active in a simulation. Because of that, the use of
this method by a module implementing such a rolling resistance model is optional.
If a power value is not provided and the aforementioned statistics modules need it,
the Rocky solver will calculate it using a first-order accurate approximation.

Parameters:
value The instantaneous power dissipated at a contact by rolling resistance.

6.10.3.11 set_sliding()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_sliding ( bool value )

© 2022, esss - all rights reserved

ROCKY api : solver manual 111

This method must be used by a module implementing a custom tangential contact

force model as it specifies whether the particles (or the particle and the triangle)
involved in the contact are sliding on each other. This method is intended to
be called from ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS, since this hook is
meant to be used to calculate and set the tangential force component for the contact.
Using it outside this hook can lead to undefined behavior. Not defining the sliding
status of the contact inside the hook can also lead to unexpected results.

Parameters:
value The sliding status of the contact just calculated using a custom contact model.

6.10.3.12 set_tangential_force()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_tangential_force ( double3 value )

This method sets the value of the tangential component of the contact force
calculated by a custom contact model. Rocky will sum this force to both
entities associated to the contact (two particles or a particle and a geometry
triangle) using the appropriate signs. This method is intended to be called from
ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS, since this hook is meant to be used
to calculate and set the tangential force component for the contact. Using it outside
this hook can lead to undefined behavior.

Parameters:
value The tangential component of the contact force just calculated using a custom model.

6.11 IRockyContactScalars struct reference

#include <rocky_contact_scalars.hpp>

6.11.1 Public member functions

 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const
 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.11.2 Detailed description

During the iterative process of a simulation, IRockyContactScalars gives access to

all contact scalars defined in the project. These contact scalars can be built-in scalars
defined in the Rocky solver, as well as custom contact scalars defined by the current
module or other active modules.

© 2022, esss - all rights reserved

ROCKY api : solver manual 112

6.11.3 Member function documentation

6.11.3.1 add_scalar()

ROCKY_FUNCTIONS void IRockyContactScalars::add_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.11.3.2 get_scalar()

ROCKY_FUNCTIONS double IRockyContactScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

6.11.3.3 max_scalar()

ROCKY_FUNCTIONS void IRockyContactScalars::max_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common
use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.11.3.4 set_scalar()

ROCKY_FUNCTIONS void IRockyContactScalars::set_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 113

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.12 IRockyContactScalarsModel struct reference

#include <rocky_contact_scalars.hpp>

6.12.1 Public member functions

 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)
 void enable_variable_dynamic_friction_coefficient ()
 void enable_variable_static_friction_coefficient ()
 void enable_variable_restitution_coefficient ()
 void enable_storage_sliding_distance ()
 void enable_storage_is_sliding_marker ()
 void enable_storage_tangential_contact_force ()
 void enable_storage_normal_relative_velocity ()
 void enable_storage_tangential_relative_velocity ()
 void enable_storage_normal_adhesion_force ()
 void enable_storage_tangential_adhesion_force ()
 void enable_storage_previous_normal_vector ()
 void enable_previous_moment_vector ()

6.12.2 Detailed description

During the setup phase of a module, an IRockyContactScalarsModel object allows

users to add new contact scalars, find contact scalars created in other modules,
or activate contact scalars known to Rocky. Contact scalars are special variables
attached to contacts that store per-contact values preserved between time iterations
during a simulation.

6.12.3 Member function documentation

© 2022, esss - all rights reserved

ROCKY api : solver manual 114

6.12.3.1 add()

int IRockyContactScalarsModel::add ( const char ∗ name, const char ∗ unit, bool output =
true )

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:

name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.12.3.2 enable_previous_moment_vector()

void IRockyContactScalarsModel::enable_previous_moment_vector ( )

This method is intended for modules implementing a custom rolling resistance

model in which the rolling resistance is updated on each time iteration. It enables
a contact scalar that can be used by a module for storing the moment calculated
at a given time iteration in order to make it available in the following iteration.
It is highly recommended to use that contact scalar instead of a regular contact
scalar, because the Rocky solver will correct the orientation of the stored vector
automatically if the contact topology is altered because of an internal reorganization
of the array of contacts (a regular contact scalar will not be corrected in such an
event).

6.12.3.3 enable_storage_is_sliding_marker()

void IRockyContactScalarsModel::enable_storage_is_sliding_marker ( )

This method enables a known-scalar that will store a marker that indicates whether
a contact is sliding or not at a given moment. Normally this marker is used only
internally in Rocky, but this method can make it available to custom models that may
need that information. When that storage has been enabled, the value of the marker
for sliding can be accessed by using the IRockyContact::get_is_sliding_marker
method.

© 2022, esss - all rights reserved

ROCKY api : solver manual 115

6.12.3.4 enable_storage_normal_adhesion_force()

void IRockyContactScalarsModel::enable_storage_normal_adhesion_force ( )

This method enables a known-scalar that stores the value of the normal component
of the adhesion force. In this way, if an adhesive force model is active in a simulation,
a custom module will have access to the value of that force. When that storage has
been enabled, the value of the normal adhesion force can be accessed by using the
IRockyContact::get_normal_adhesion_force method.

6.12.3.5 enable_storage_normal_relative_velocity()

void IRockyContactScalarsModel::enable_storage_normal_relative_velocity ( )

This method enables a known-scalar that stores the value of the normal component
of the relative velocity at a contact. In this way that value, which is normally
calculated internally by the Rocky solver and used on its own calculations,
will be made available for custom modules as well. This can be preferable
to the use of the IRockyContact::calculate_relative_velocity method, since
that calculation may be expensive. When its storage has been enabled, the
value of the normal relative velocity component can be accessed by using the
IRockyContact::get_normal_relative_velocity method.

6.12.3.6 enable_storage_previous_normal_vector()

void IRockyContactScalarsModel::enable_storage_previous_normal_vector ( )

This method enables a known-scalar that stores automatically the value of the
contact's normal unit vector at the end of a time iteration, with the purpose
of making it available during the next time iteration. If the storage of this
vector has been enabled, it can be accessed during a simulation by using the
IRockyContact::get_previous_normal_vector method. By comparing this vector
to the current normal unit vector, a custom module will be able to determine if
a change on the contact's normal direction has occurred between iterations. The
Rocky solver will correct the orientation of this vector automatically if the contact
topology is altered because of an internal reorganization of the array of contacts (a
regular contact scalar will not be corrected in such an event).

6.12.3.7 enable_storage_sliding_distance()

void IRockyContactScalarsModel::enable_storage_sliding_distance ( )

This method enables a known-scalar that stores the value calculated for the sliding
distance during the processing of the contact forces. In this way, that value will be

© 2022, esss - all rights reserved

ROCKY api : solver manual 116

accessible to custom models that may need it for their own calculations. The sliding
distance is the distance that a contact point moves parallel to the tangential contact
plane during a timestep. When its storage has been enabled, the value of the sliding
distance can be accessed by using the IRockyContact::get_sliding_distance
method.

6.12.3.8 enable_storage_tangential_adhesion_force()

void IRockyContactScalarsModel::enable_storage_tangential_adhesion_force ( )

This method enables a known-scalar that stores the value of the tangential
component of the adhesion force. Only some external modules, such as the
Liquid Bridge Model module, implement a model in which the adhesion force
may have a tangential component. If one of such modules is active in a
simulation, a custom module will have access to the value of that force when
its storage has been enabled with this method. Then, during the simula-
tion, the value of the tangential adhesion force can be accessed by using the
IRockyContact::get_tangential_adhesion_force method.

6.12.3.9 enable_storage_tangential_contact_force()

void IRockyContactScalarsModel::enable_storage_tangential_contact_force ( )

This method enables a known-scalar that makes available to custom modules the
tangential force vector that is calculated by any contact tangential force model active
in a simulation. The value of this force is not always automatically accessible by
custom models. For instance, if users want to use the tangential force value when
the Coulomb Limit or any other custom contact tangential force model is active,
they will need to enable its storage using this method. When that storage has
been enabled, the value of the tangential force vector can be accessed by using the
IRockyContact::get_tangential_contact_force method.

6.12.3.10 enable_storage_tangential_relative_velocity()

void IRockyContactScalarsModel::enable_storage_tangential_relative_velocity ( )

This method enables a known-scalar that stores the value of the normal component
of the relative velocity at a contact. In this way that value, which is normally
calculated internally by the Rocky solver and used on its own calculations,
will be made available for custom modules as well. This can be preferable
to the use of the IRockyContact::calculate_relative_velocity method, since
that calculation may be expensive. When its storage has been enabled, the

© 2022, esss - all rights reserved

ROCKY api : solver manual 117

value of the tangential relative velocity vector can be accessed by using the
IRockyContact::get_tangential_relative_velocity method.

6.12.3.11 enable_variable_dynamic_friction_coefficient()

void IRockyContactScalarsModel::enable_variable_dynamic_friction_coefficient ( )

This method enables the dynamic coefficient of friction as a variable property for
contacts that will override the constant values specified per material interaction in
the Rocky UI. When a custom module enables this variable property, it becomes
responsible for setting a custom value for every contact in the simulation by using
the IRockyContact::set_dynamic_friction_coefficient method.

6.12.3.12 enable_variable_restitution_coefficient()

void IRockyContactScalarsModel::enable_variable_restitution_coefficient ( )

This method enables a known-scalar that defines the restitution coefficient as a

variable property at contacts. When this scalar is enabled, a different value of the
restitution coefficient can be specified for each contact that arises in a simulation,
using the IRockyContact::set_restitution_coefficient method. In this case,
that value will override the constant values specified for this property through the
Rocky UI.

6.12.3.13 enable_variable_static_friction_coefficient()

void IRockyContactScalarsModel::enable_variable_static_friction_coefficient ( )

This method enables the static coefficient of friction as a variable property for
contacts that will override the constant values specified per material interaction in
the Rocky UI. When a custom module enables this variable property, it becomes
responsible for setting a custom value for every contact in the simulation by using
the IRockyContact::set_static_friction_coefficient method.

6.12.3.14 find()

int IRockyContactScalarsModel::find ( const char ∗ name )

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:
name The name given to the scalar at the moment of its creation.

© 2022, esss - all rights reserved

ROCKY api : solver manual 118

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

6.12.3.15 reset()

void IRockyContactScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.

6.12.3.16 set_dimension()

void IRockyContactScalarsModel::set_dimension ( int scalar_index, double dimension_factor

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

6.13 IRockyCurveCollectionData struct reference

#include <rocky_time_curve_data_api.hpp>

6.13.1 Public member functions

 void create_particles_dataset (const std::string &name, const std::string &unit)
 void create_geometry_dataset (int geometry_id, const std::string &name, const std::string &unit)
 void create_dataset (const std::string &owner_name, const std::string &name, const std::string &unit)
 void create_particles_curve (const std::string &domain_dataset, const std::string &image_dataset)
 void create_geometry_curve (int geometry_id, const std::string &domain_dataset, const std::string &image_dataset)
 void add_curve (const std::string &owner_name, const std::string &domain_dataset, const std::string &image_dataset)
 void setup_particles_dataset_dimension (const std::string &name, double dimension)
 void setup_geometry_dataset_dimension (int geometry_id, const std::string &name, double dimension)
 void setup_dataset_dimension (const std::string &owner_name, const std::string &name, double dimension)
 void update_particles_dataset (const std::string &name, const double ∗dataset, size_t size)

© 2022, esss - all rights reserved

ROCKY api : solver manual 119

 void update_geometry_dataset (int geometry_id, const std::string &name, const double ∗dataset, size_t size)
 void update_dataset (const std::string &owner_name, const std::string &name, const double ∗dataset, size_t size)
 void create_particles_time_curve (const std::string &name, const std::string &unit)
 void create_geometry_time_curve (int geometry_id, const std::string &name, const std::string &unit)
 void create_time_curve (const std::string &owner_name, const std::string &name, const std::string &unit)
 void setup_particles_time_curve_dimension (const std::string &name, double dimension)
 void setup_geometry_time_curve_dimension (int geometry_id, const std::string &name, double dimension)
 void setup_time_curve_dimension (const std::string &owner_name, const std::string &name, double dimension)
 void update_particles_time_curve (const std::string &name, double value)
 void update_geometry_time_curve (int geometry_id, const std::string &name, double value)
 void update_time_curve (const std::string &owner_name, const std::string &name, double value)

6.13.2 Detailed description

IRockyCurveCollectionData is a data structure intended to hold data that will be

used by Rocky to create a custom collection of cross plot curves and/or time curves
for particles and geometries.
A curve is composed of a pair of domain and image datasets. A dataset is a set
of values that may change over time in values and size. When creating a dataset,
one must provide its name and unit. During the simulation, such datasets must be
updated with custom data, which will be written on disk by Rocky at output times.
The most adequate hook to perform that data update is ROCKY_PLUGIN_PRE_OUTPUT,
because it is executed immediately before the data output. However, depending on
the particular needs of the module, that operation can be done in other hooks as
well. After an output operation, all dataset values are automatically erased, and
must be updated again for the next output. At any given output, a domain and an
image datasets for a cross-plot curve must have the same size, otherwise an error
will be thrown.

6.13.3 Member function documentation

6.13.3.1 add_curve()

void IRockyCurveCollectionData::add_curve ( const std::string & owner_name, const std::string

& domain_dataset, const std::string & image_dataset )

This method creates a curve by specifying the names of domain and image datasets.
Such curve is related to a given named entity. Shown within the Rocky UI as a
curve.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 120

owner_name The entity unique identifier (string)

domain_dataset The name of the domain dataset.

image_dataset The unit of the image dataset.

6.13.3.2 create_dataset()

void IRockyCurveCollectionData::create_dataset ( const std::string & owner_name, const std←-

::string & name, const std::string & unit )

This method creates a dataset by specifying its name and the unit of the physical
magnitude associated. Such dataset is related to a given named owner entity.
Initially empty, the dataset must be updated with values during the simulation by
using IRockyCurveCollectionData::update_dataset.

Parameters:
owner_name The entity unique identifier (string)

name The name of the dataset.

unit The unit of the related magnitude, which will be associated to an axis of the cross
plot where the dataset will be displayed.

6.13.3.3 create_geometry_curve()

void IRockyCurveCollectionData::create_geometry_curve ( int geometry_id, const std::string

& domain_dataset, const std::string & image_dataset )

This method creates a curve by specifying the names of domain and image datasets.
Such curve is related to a geometry. Shown within the Rocky UI as a curve.

Parameters:
geometry_id The geometry unique identifier (index)

domain_dataset The name of the domain dataset.

image_dataset The unit of the image dataset.

6.13.3.4 create_geometry_dataset()

void IRockyCurveCollectionData::create_geometry_dataset ( int geometry_id, const std::string

& name, const std::string & unit )

This method creates a dataset related to a geometry by specifying its name and the
unit of the associated physical magnitude. Initially empty, the dataset must be up-
dated with values by using IRockyCurveCollectionData::update_geometry_dataset.

Parameters:
geometry_id The geometry unique identifier (index)

name The name of the dataset.

unit The unit of the related magnitude, which will be associated to an axis of the cross
plot where the dataset will be displayed.

© 2022, esss - all rights reserved

ROCKY api : solver manual 121

6.13.3.5 create_geometry_time_curve()

void IRockyCurveCollectionData::create_geometry_time_curve ( int geometry_id, const std←-

::string & name, const std::string & unit )

This method creates a time curve associated to a specific geometry, by spec-

ifying its name and the unit of the physical magnitude associated. Initially
empty, the time curve must be filled with data during a simulation by using
IRockyCurveCollectionData::update_geometry_time_curve.

Parameters:
geometry_id The geometry unique identifier (index)

name The name of the time curve. Shown within the Rocky UI as the curve label.

unit The unit of the magnitude displayed in the vertical axis of the time curve.

6.13.3.6 create_particles_curve()

void IRockyCurveCollectionData::create_particles_curve ( const std::string & domain_dataset,

const std::string & image_dataset )

This method creates a curve by specifying the names of domain and image datasets.
Such curve is related to particles. Shown within the Rocky UI as a curve.

Parameters:
domain_dataset The name of the domain dataset.
image_dataset The unit of the image dataset.

6.13.3.7 create_particles_dataset()

void IRockyCurveCollectionData::create_particles_dataset ( const std::string & name, const

std::string & unit )

This method creates a dataset related to particles by specifying its name and the unit
of the physical magnitude associated. Initially empty, the dataset must be updated
with values by using IRockyCurveCollectionData::update_particles_dataset
during the simulation.

Parameters:
name The name of the dataset.
unit The unit of the related magnitude, which will be associated to an axis of the cross plot
where the dataset will be displayed.

6.13.3.8 create_particles_time_curve()

void IRockyCurveCollectionData::create_particles_time_curve ( const std::string & name, const

std::string & unit )

© 2022, esss - all rights reserved

ROCKY api : solver manual 122

This method creates a time curve associated to particles by specifying its name
and the unit of the physical magnitude associated. Initially empty, the curve must be
filled with data by using IRockyCurveCollectionData::update_particles_time_curve
during the simulation.

Parameters:
name The name of the time curve. Shown within the Rocky UI as the curve label.

unit The unit of the magnitude displayed in the vertical axis of the time curve.

6.13.3.9 create_time_curve()

void IRockyCurveCollectionData::create_time_curve ( const std::string & owner_name, const

std::string & name, const std::string & unit )

This method creates a time curve associated to a given entity by specifying its name
and the unit of the physical magnitude associated. Initially empty, the time curve
must be filled with data by using IRockyCurveCollectionData::update_time_curve
during the simulation.

Parameters:
owner_name The entity unique identifier (string)

name The name of the time curve. Shown within the Rocky UI as the curve label.

unit The unit of the magnitude displayed in the vertical axis of the time curve.

6.13.3.10 setup_dataset_dimension()

void IRockyCurveCollectionData::setup_dataset_dimension ( const std::string & owner_name, const

std::string & name, double dimension )

The purpose of this method is to associate a dimensional factor to a dataset. This

factor will be used to nondimensionalize their values for calculations. Dimensional
factors for the fundamental magnitudes are provided by functions of a IRockyModel
object.

Parameters:
owner_name The entity unique identifier (string)

name The name of the dataset.

dimension The appropriate dimensional factor for the dataset.

6.13.3.11 setup_geometry_dataset_dimension()

void IRockyCurveCollectionData::setup_geometry_dataset_dimension ( int geometry_id, const

std::string & name, double dimension )

The purpose of this method is to associate a dimensional factor to a dataset.

This factor will be used to nondimensionalize their values for the calculations.

© 2022, esss - all rights reserved

ROCKY api : solver manual 123

Dimensional factors for the fundamental magnitudes are provided by functions of a

IRockyModel object.

Parameters:
geometry_id The geometry unique identifier (index)

name The name of the dataset.

dimension The appropriate dimensional factor for the dataset.

6.13.3.12 setup_geometry_time_curve_dimension()

void IRockyCurveCollectionData::setup_geometry_time_curve_dimension ( int geometry_id, const

std::string & name, double dimension )

The purpose of this method is to associate a dimensional factor to a time curve. This
factor will be used to nondimensionalize their values. Dimensional factors for the
fundamental magnitudes are provided by functions of a IRockyModel object.

Parameters:
geometry_id The geometry unique identifier (index)

name The name of the time curve.

dimension The appropriate dimensional factor for the time curve.

6.13.3.13 setup_particles_dataset_dimension()

void IRockyCurveCollectionData::setup_particles_dataset_dimension ( const std::string & name,

double dimension )

The purpose of this method is to associate a dimensional factor to a dataset.

This factor will be used to nondimensionalize their values for the calculations.
Dimensional factors for the fundamental magnitudes are provided by functions of a
IRockyModel object.

Parameters:
name The name of the dataset.
dimension The appropriate dimensional factor for the dataset.

6.13.3.14 setup_particles_time_curve_dimension()

void IRockyCurveCollectionData::setup_particles_time_curve_dimension ( const std::string &

name, double dimension )

The purpose of this method is to associate a dimensional factor to a time curve. This
factor will be used to nondimensionalize their values. Dimensional factors for the
fundamental magnitudes are provided by functions of a IRockyModel object.

Parameters:
name The name of the time curve.
dimension The appropriate dimensional factor for the time curve.

© 2022, esss - all rights reserved

ROCKY api : solver manual 124

6.13.3.15 setup_time_curve_dimension()

void IRockyCurveCollectionData::setup_time_curve_dimension ( const std::string & owner_name,

const std::string & name, double dimension )

The purpose of this method is to associate a dimensional factor to a time curve. This
factor will be used to nondimensionalize their values. Dimensional factors for the
fundamental magnitudes are provided by functions of a IRockyModel object.

Parameters:
owner_name The entity unique identifier (string)

name The name of the time curve. Shown within the Rocky UI as the curve label.

dimension The appropriate dimensional factor for the time curve.

6.13.3.16 update_dataset()

void IRockyCurveCollectionData::update_dataset ( const std::string & owner_name, const std←-

::string & name, const double ∗ dataset, size_t size )

This method updates a dataset by inserting new dataset values. Intended to be used
only at output times. The dataset to be added should correspond to the output time
at which this method is called. It only works with datasets previously created using
IRockyCurveCollectionData::create_dataset, otherwise it throws an error.

Parameters:
owner_name The entity unique identifier (string)

name The name of the dataset.

dataset A data pointer to the new dataset data to be copied into dataset.

size The number of elements of the given dataset

6.13.3.17 update_geometry_dataset()

void IRockyCurveCollectionData::update_geometry_dataset ( int geometry_id, const std::string

& name, const double ∗ dataset, size_t size )

This method updates a dataset by inserting new dataset values. Intended to be used
only at output times. The dataset to be added should correspond to the output time
at which this method is called. It only works with datasets previously created using
IRockyCurveCollectionData::create_geometry_dataset, otherwise it throws an
error.

Parameters:
geometry_id The geometry unique identifier (index)

name The name of the dataset.

dataset A data pointer to the new dataset data to be copied into dataset.

size The number of elements of the given dataset

© 2022, esss - all rights reserved

ROCKY api : solver manual 125

6.13.3.18 update_geometry_time_curve()

void IRockyCurveCollectionData::update_geometry_time_curve ( int geometry_id, const std←-

::string & name, double value )

This method updates a time curve by inserting a new value. Intended to be used
only at output times. The value to be added should correspond to the output time at
which this method is called. It only works with time curves previously created using
IRockyCurveCollectionData::create_geometry_time_curve, otherwise it throws
an error.

Parameters:
geometry_id The geometry unique identifier (index)

name The name of the time curve.

value The value to be appended into the curve.

6.13.3.19 update_particles_dataset()

void IRockyCurveCollectionData::update_particles_dataset ( const std::string & name, const

double ∗ dataset, size_t size )

This method updates a dataset by inserting new values. Intended to be used only
at output times. The dataset to be added should correspond to the output time at
which this method is called. It only works with datasets previously created using
IRockyCurveCollectionData::create_particles_dataset, otherwise it throws an
error.

Parameters:
name The name of the dataset.
dataset A data pointer to the new dataset data to be copied into dataset.

size The number of elements of the given dataset

6.13.3.20 update_particles_time_curve()

void IRockyCurveCollectionData::update_particles_time_curve ( const std::string & name, double

value )

This method updates a time curve by inserting a new value. Intended to be used
only at output times. The value to be added should correspond to the output time at
which this method is called. It only works with time curves previously created using
IRockyCurveCollectionData::create_particles_time_curve, otherwise it throws
an error.

Parameters:
name The name of the time curve.
value The value to be appended into the curve.

© 2022, esss - all rights reserved

ROCKY api : solver manual 126

6.13.3.21 update_time_curve()

void IRockyCurveCollectionData::update_time_curve ( const std::string & owner_name, const

std::string & name, double value )

This method updates a time curve by inserting a new value. Intended to be used
only at output times. The value to be added should correspond to the output time at
which this method is called. It only works with time curves previously created using
IRockyCurveCollectionData::create_time_curve, otherwise it throws an error.

Parameters:

owner_name The entity unique identifier (string)

name The name of the time curve.

value The value to be appended into the curve.

6.14 IRockyCFDProperties struct reference

#include <rocky_cfd.hpp>

6.14.1 Public member functions

 ROCKY_FUNCTIONS double get_fluid_density () const
 ROCKY_FUNCTIONS double get_fluid_viscosity () const
 ROCKY_FUNCTIONS double get_fluid_temperature () const
 ROCKY_FUNCTIONS double get_fluid_specific_heat () const
 ROCKY_FUNCTIONS double get_fluid_thermal_conductivity () const
 ROCKY_FUNCTIONS double3 get_fluid_pressure_gradient () const
 ROCKY_FUNCTIONS double3 compute_fluid_vorticity () const
 ROCKY_FUNCTIONS double3 get_relative_velocity () const
 ROCKY_FUNCTIONS double get_reynolds_number () const
 ROCKY_FUNCTIONS double compute_vorticity_reynolds_number () const
 ROCKY_FUNCTIONS double compute_relative_angular_reynolds_number (const double3 &particle_angular_velocity) const
 ROCKY_FUNCTIONS double get_prandtl_number () const
 ROCKY_FUNCTIONS double get_solid_fraction () const
 ROCKY_FUNCTIONS double get_cell_volume () const
 ROCKY_FUNCTIONS IRockyFluidScalars get_scalars () const
 ROCKY_FUNCTIONS double get_cfd_time_step () const

6.14.2 Detailed description

IRockyCFDProperties gives access to data and utility methods commonly needed

for calculating interaction magnitudes between the fluid flow and a particle. The

© 2022, esss - all rights reserved

ROCKY api : solver manual 127

property values returned by those methods are referred either to a particle, or the
CFD cell in which that particle is currently located, or both. In the special case
of a 1-way constant coupling mode, as there is no CFD mesh associated, the fluid
properties returned are the constant values prescribed through the Rocky UI.

6.14.3 Member function documentation

6.14.3.1 compute_fluid_vorticity()

ROCKY_FUNCTIONS double3 IRockyCFDProperties::compute_fluid_vorticity ( ) const

Returns:
The vorticity vector associated to the fluid flow within the CFD cell in which the interacting particle
is located. The vorticity is defined as the curl of the fluid velocity.

6.14.3.2 compute_relative_angular_reynolds_number()

ROCKY_FUNCTIONS double IRockyCFDProperties::compute_relative_angular_reynolds_number ( const

double3 & particle_angular_velocity ) const

Returns:
The Reynolds number value, based on the relative angular velocity and the particle's equivalent
diameter, as defined in equation 3.80 of the DEM-CFD Coupling Technical Manual. Torque laws
are commonly expressed using this Reynolds number.

6.14.3.3 compute_vorticity_reynolds_number()

ROCKY_FUNCTIONS double IRockyCFDProperties::compute_vorticity_reynolds_number ( ) const

Returns:
The Reynolds number value, based on the flow vorticity and the particle's equivalent diameter, as
defined in equation 3.70 of the DEM-CFD Coupling Technical Manual. Lift coefficients are usually
expressed as functions of this Reynolds number.

6.14.3.4 get_cell_volume()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_cell_volume ( ) const

Returns:
The volume of the CFD cell in which the interacting particle is located.

6.14.3.5 get_cfd_time_step()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_cfd_time_step ( ) const

Returns:
The CFD time step

© 2022, esss - all rights reserved

ROCKY api : solver manual 128

6.14.3.6 get_fluid_density()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_fluid_density ( ) const

Returns:
The value of the fluid density within the CFD cell in which the interacting particle is located.

6.14.3.7 get_fluid_pressure_gradient()

ROCKY_FUNCTIONS double3 IRockyCFDProperties::get_fluid_pressure_gradient ( ) const

Returns:
The pressure gradient in the fluid within the CFD cell in which the interacting particle is located,
expressed in Cartesian coordinates.

6.14.3.8 get_fluid_specific_heat()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_fluid_specific_heat ( ) const

Returns:
The value of the fluid specific heat within the CFD cell in which the interacting particle is located.

6.14.3.9 get_fluid_temperature()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_fluid_temperature ( ) const

Returns:
The value of the fluid temperature within the CFD cell in which the interacting particle is located.
This temperature will be available only if the energy equation is solved in Fluent and/or thermal
modeling is enabled in Rocky.

6.14.3.10 get_fluid_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_fluid_thermal_conductivity ( ) const

Returns:
The value of the fluid thermal conductivity within the CFD cell in which the interacting particle is
located.

6.14.3.11 get_fluid_viscosity()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_fluid_viscosity ( ) const

Returns:
The value of the fluid absolute viscosity within the CFD cell in which the interacting particle is
located.

6.14.3.12 get_prandtl_number()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_prandtl_number ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 129

Returns:
The Prandtl number value, defined as the ratio of the fluid's momentum diffusivity to its thermal
diffusivity. In function of fluid basic properties, it is given by equation (4.4) of the DEM-CFD
Coupling Technical Manual.

6.14.3.13 get_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyCFDProperties::get_relative_velocity ( ) const

Returns:
The relative velocity vector in Cartesian coordinates. In this context, the relative velocity is defined
as the difference between the fluid velocity and the particle velocity.

6.14.3.14 get_reynolds_number()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_reynolds_number ( ) const

Returns:
The Reynolds number value, based on the relative velocity and the particle's equivalent diameter,
as defined in equation 3.6 of the DEM-CFD Coupling Technical Manual. Drag coefficients in most
of the drag laws found in the literature are expressed as functions of this Reynolds number.

6.14.3.15 get_scalars()

ROCKY_FUNCTIONS IRockyFluidScalars IRockyCFDProperties::get_scalars ( ) const

Returns:
An IRockyFluidScalars object that gives access to the values of all CFD fluid scalars defined in the
project at the CFD cell in which the interacting particle is located.

6.14.3.16 get_solid_fraction()

ROCKY_FUNCTIONS double IRockyCFDProperties::get_solid_fraction ( ) const

Returns:
The solid fraction at the CFD cell in which the interacting particle is located. This parameter is
defined as the ratio between the volume of the particles within that cell to the volume of the cell
itself. In Fluent Two Way cases, the value of the solid fraction may be altered by a Lagrangian-
to-Eulerian mapping procedure. For more details, please refer to section 6.3 of the DEM-CFD
Coupling Technical Manual.

6.15 IRockyDeviceModel struct reference

#include <rocky_model_api.hpp>

6.15.1 Public member functions

 ROCKY_FUNCTIONS double get_time_step () const
 ROCKY_FUNCTIONS double get_current_time () const
 ROCKY_FUNCTIONS IRockyParticleCloudPoint get_particle_cloud_point (int point_cloud_index, const IRockyParticle &particle)

© 2022, esss - all rights reserved

ROCKY api : solver manual 130

6.15.2 Detailed description

IRockyDeviceModel includes auxiliary functions that are available only during the
execution of a simulation. Hooks such as ROCKY_PLUGIN_PRE_FORCE..., ROCKY_←-
PLUGIN_POST_FORCE..., and ROCKY_PLUGIN_PRE_MOVE..., provide an IRockyDeviceModel
object as a parameter.

6.15.3 Member function documentation

6.15.3.1 get_current_time()

ROCKY_FUNCTIONS double IRockyDeviceModel::get_current_time ( ) const

Returns:
The value of the current time in the simulation.

6.15.3.2 get_particle_cloud_point()

ROCKY_FUNCTIONS IRockyParticleCloudPoint IRockyDeviceModel::get_particle_cloud_point ( int

point_cloud_index, const IRockyParticle & particle )

This function gets an auxiliary object that gives access to cloud point values of the
nearest point to a given particle.

Parameters:
point_cloud_index The index that uniquely identifies a point cloud dataset.

particle A IRockyParticle whose position is used to determine the nearest cloud

point.

Returns:
An IRockyParticleCloudPoint object, which can be used to get cloud point values of the nearest
point to the particle passed as argument. For more information about point clouds, please refer to
the Rocky User Manual.

6.15.3.3 get_time_step()

ROCKY_FUNCTIONS double IRockyDeviceModel::get_time_step ( ) const

Returns:
The value of the simulation timestep.

6.16 IRockyFluidScalars struct reference

#include <rocky_fluid_scalars.hpp>

© 2022, esss - all rights reserved

ROCKY api : solver manual 131

6.16.1 Public member functions

 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const
 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.16.2 Detailed description

During the iterative process of a simulation, IRockyFluidScalars gives access to

all fluid scalars defined in the project. These fluid scalars can be built-in scalars
defined in the Rocky solver, or custom fluid scalars defined by the current module
or other active modules.

6.16.3 Member function documentation

6.16.3.1 add_scalar()

ROCKY_FUNCTIONS void IRockyFluidScalars::add_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.16.3.2 get_scalar()

ROCKY_FUNCTIONS double IRockyFluidScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

© 2022, esss - all rights reserved

ROCKY api : solver manual 132

6.16.3.3 max_scalar()

ROCKY_FUNCTIONS void IRockyFluidScalars::max_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common
use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.16.3.4 set_scalar()

ROCKY_FUNCTIONS void IRockyFluidScalars::set_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.17 IRockyFluidScalarsModel struct reference

#include <rocky_fluid_scalars.hpp>

6.17.1 Public member functions

 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)

6.17.2 Detailed description

An IRockyFluidScalarsModel allows users to add new fluid scalars, or find fluid

scalars created in other modules, all during the setup phase of a module. Fluid
scalars are special variables attached to CFD cell elements that store per-cell values
preserved between simulation time iterations.

© 2022, esss - all rights reserved

ROCKY api : solver manual 133

6.17.3 Member function documentation

6.17.3.1 add()

int IRockyFluidScalarsModel::add ( const char ∗ name, const char ∗ unit, bool output = true
)

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:

name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.17.3.2 find()

int IRockyFluidScalarsModel::find ( const char ∗ name )

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:

name The name given to the scalar at the moment of its creation.

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

6.17.3.3 reset()

void IRockyFluidScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.

© 2022, esss - all rights reserved

ROCKY api : solver manual 134

6.17.3.4 set_dimension()

void IRockyFluidScalarsModel::set_dimension ( int scalar_index, double dimension_factor )

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:
scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

6.18 IRockyGeometriesMotionData struct reference

#include <rocky_boundary_api.hpp>

6.18.1 Public member functions

 unsigned int get_number_of_geometries () const
 IRockyGeometryMotionData get_geometry (unsigned int id) const
 IRockyGeometryMotionData get_geometry (const std::string &name) const

6.18.2 Detailed description

IRockyGeometriesMotionData is an interface for a list of geometries motions in

Rocky. The list of geometries motions represented by this interface contains all
geometries in Rocky, and they may or may not have a motion applied in Rocky's
last simulation timestep. The geometries motions can be generated based upon the
IDs of the geometries, which are numbered sequentially starting from zero, or from
the names assigned to the geometries in the Rocky UI.

6.18.3 Member function documentation

6.18.3.1 get_geometry() [1/2]

IRockyGeometryMotionData IRockyGeometriesMotionData::get_geometry ( const std::string & name

) const

Gets a geometry's motion given the geometry's name. If the provided name does not
correspond to an existing geometry in Rocky, this method will raise an exception.

© 2022, esss - all rights reserved

ROCKY api : solver manual 135

Parameters:
name The name assigned in Rocky to an existing geometry.

Returns:
A geometry's motion.

6.18.3.2 get_geometry() [2/2]

IRockyGeometryMotionData IRockyGeometriesMotionData::get_geometry ( unsigned int id ) const

Gets a geometry's motion given the geometry's Rocky ID. If the provided ID does
not correspond to an existing geometry in Rocky, this method will raise an exception.

Parameters:
id The index assigned in Rocky to an existing geometry.

Returns:
A geometry's motion.

6.18.3.3 get_number_of_geometries()

unsigned int IRockyGeometriesMotionData::get_number_of_geometries ( ) const

Returns:
The number of geometries in the Rocky project.

6.19 IRockyGeometryMotionData struct reference

#include <rocky_boundary_api.hpp>

6.19.1 Public member functions

 int get_id () const
 std::string get_name () const
 double3 get_force () const
 double3 get_moment () const
 double3 get_position () const
 double3 get_translational_velocity () const
 double4 get_orientation_quaternion () const
 double3 get_orientation_euler_angles () const
 double3 get_rotational_velocity () const
 void set_position (double3 position)
 void set_translational_velocity (double3 v)
 void set_orientation (double4 quat)
 void set_orientation_angles (double3 angles)
 void set_rotational_velocity (double3 w)

© 2022, esss - all rights reserved

ROCKY api : solver manual 136

6.19.2 Detailed description

IRockyGeometryMotionData is an interface for a geometry motion in Rocky. A

geometry motion represents the information from the motion applied to the
geometry in Rocky's last simulation timestep. This information includes for Rocky's
current simulation timestep, the forces and moments from the particles that are
being applied to the geometry, and also the position, translational velocity, rotational
velocity and orientation of the geometry from the previous timestep's motion. The
information represented in a geometry motion are the forces and moments from
the particles simulation, the position, translational velocity, rotational velocity and
orientation of the geometry from the previous motion. To move the geometry within
Rocky's current simulation timestep, the same motion information, i.e. (the new
position, translational velocity, rotational velocity and orientation of the geometry)
must be defined as within the previous timestep. If no motion is applied to the
geometry, nothing is required to be set. If the geometry has no motion applied to
it, the geometry's translational and rotational velocities are zero and its position
and orientation are equal to the ones set at the end of the previous timestep. All
property and variable values made available through IRockyGeometryMotionData
are dimensionless.
Attention:
The geometry's gravity center is the reference position Rocky uses for the geometry's motions. Thus,
the geometry's gravity center will have a new position after each motion applied.

6.19.3 Member function documentation

6.19.3.1 get_force()

double3 IRockyGeometryMotionData::get_force ( ) const

Returns:
The Cartesian components of the force applied by Rocky to the geometry.

6.19.3.2 get_id()

int IRockyGeometryMotionData::get_id ( ) const

Returns:
The ID of the geometry.

6.19.3.3 get_moment()

double3 IRockyGeometryMotionData::get_moment ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 137

Returns:
The Cartesian components of the moment applied by Rocky to the geometry.

6.19.3.4 get_name()

std::string IRockyGeometryMotionData::get_name ( ) const

Returns:
The name of the geometry.

6.19.3.5 get_orientation_euler_angles()

double3 IRockyGeometryMotionData::get_orientation_euler_angles ( ) const

Returns:
A vector whose components are the Euler angles that define the orientation of the geometry. In this
vector, the x-component is the roll angle, the y-component is the pitch angle and the z-component
is the yaw angle.

6.19.3.6 get_orientation_quaternion()

double4 IRockyGeometryMotionData::get_orientation_quaternion ( ) const

Returns:
The orientation of the geometry expressed as a quaternion (w, x, y and z).

6.19.3.7 get_position()

double3 IRockyGeometryMotionData::get_position ( ) const

Returns:
The Cartesian coordinates of the reference position for the motion, which coincides with the
geometry's gravity center.

6.19.3.8 get_rotational_velocity()

double3 IRockyGeometryMotionData::get_rotational_velocity ( ) const

Returns:
The Cartesian components of the geometry's rotational velocity.

6.19.3.9 get_translational_velocity()

double3 IRockyGeometryMotionData::get_translational_velocity ( ) const

Returns:
The Cartesian components of the geometry's translational velocity.

© 2022, esss - all rights reserved

ROCKY api : solver manual 138

6.19.3.10 set_orientation()

void IRockyGeometryMotionData::set_orientation ( double4 quat )

Sets the geometry's new orientation (quaternion) according to the motion that was
applied.

Parameters:
quat The geometry's new orientation expressed as a quaternion (w, x, y and z).

6.19.3.11 set_orientation_angles()

void IRockyGeometryMotionData::set_orientation_angles ( double3 angles )

Sets the geometry's new orientation in Euler angles according to the motion that
was applied.

Parameters:
angles A vector whose components are the Euler angles that define the new orientation of
the geometry. In this vector, the x-component is the roll angle, the y-component is the
pitch angle and the z-component is the yaw angle.

6.19.3.12 set_position()

void IRockyGeometryMotionData::set_position ( double3 position )

Sets the new position for the geometry according to the motion that was applied.
Rocky uses the geometry's gravity center as the reference position for the geometry's
motions. Thus, the geometry's gravity center will have a new position after each
motion applied.

Parameters:
position The Cartesian components of the geometry's new position, which is equal to the
new location of its gravity center.

6.19.3.13 set_rotational_velocity()

void IRockyGeometryMotionData::set_rotational_velocity ( double3 w )

Sets the geometry's new rotational velocity according to the motion that was applied.

Parameters:
w The Cartesian components of the geometry's new rotational velocity.

6.19.3.14 set_translational_velocity()

void IRockyGeometryMotionData::set_translational_velocity ( double3 v )

© 2022, esss - all rights reserved

ROCKY api : solver manual 139

Sets the geometry's new translational velocity according to the motion that was
applied.

Parameters:
v The Cartesian components of the geometry's new translational velocity.

6.20 IRockyGeometryTriangle struct reference

#include <rocky_boundary_api.hpp>

6.20.1 Public member functions

 ROCKY_FUNCTIONS IRockyMaterial get_material () const
 ROCKY_FUNCTIONS double3 get_normal_unit_vector () const
 ROCKY_FUNCTIONS double get_area () const
 ROCKY_FUNCTIONS double3 get_centroid () const
 ROCKY_FUNCTIONS int get_geometry_index () const
 ROCKY_FUNCTIONS int get_material_index () const
 ROCKY_FUNCTIONS double3 get_translational_velocity (double current_time) const
 ROCKY_FUNCTIONS double3 get_geometry_rotational_velocity () const
 ROCKY_FUNCTIONS double3 get_geometry_rotation_center () const
 ROCKY_FUNCTIONS double get_temperature () const
 ROCKY_FUNCTIONS void set_temperature (double value)
 ROCKY_FUNCTIONS bool is_adiabatic () const
 ROCKY_FUNCTIONS double get_thermal_conductivity () const
 ROCKY_FUNCTIONS void set_thermal_conductivity (double value)
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS void set_poisson_ratio (double value)
 ROCKY_FUNCTIONS IRockyTriangleScalars get_scalars ()

6.20.2 Detailed description

IRockyGeometryTriangle is an interface for the internal geometry triangle object in

Rocky. A geometry triangle is a code representation of an individual triangle making
up a geometry. IRockyGeometryTriangle is intended for use in all the operations
performed during the time iterative process, involving geometry triangles. It has
access methods to some geometric properties, as well as triangle scalars, which are
special variables that store values per triangle that are preserved between time
iterations. Values of triangle scalars can be displayed in a 3D window as any other
built-in geometry triangle property in Rocky. All property and variable values made
available through IRockyGeometryTriangle are dimensionless.
Attention:
IRockyGeometryTriangle replaces IRockyBoundaryTriangle in Rocky v4.5 or newer.

© 2022, esss - all rights reserved

ROCKY api : solver manual 140

6.20.3 Member function documentation

6.20.3.1 get_area()

ROCKY_FUNCTIONS double IRockyGeometryTriangle::get_area ( ) const

Returns:
The unsigned area of the geometry triangle.

6.20.3.2 get_centroid()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangle::get_centroid ( ) const

Returns:
The centroid point of the geometry triangle in Cartesian coordinates.

6.20.3.3 get_geometry_index()

ROCKY_FUNCTIONS int IRockyGeometryTriangle::get_geometry_index ( ) const

Returns:
The index that uniquely identifies the geometry to which the geometry triangle belongs.

6.20.3.4 get_geometry_rotation_center()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangle::get_geometry_rotation_center ( ) const

Returns:
The Cartesian coordinates of the rotation center of the motion frame attached to the geometry to
which the triangle belongs.

6.20.3.5 get_geometry_rotational_velocity()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangle::get_geometry_rotational_velocity ( ) const

Returns:
The rotational velocity vector of the geometry to which the triangle belongs, expressed in Cartesian
coordinates.

6.20.3.6 get_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyGeometryTriangle::get_material ( ) const

Returns:
An IRockyMaterial object that gives access to the values of physical properties associated to the
material from which the geometry triangle is made.

6.20.3.7 get_material_index()

ROCKY_FUNCTIONS int IRockyGeometryTriangle::get_material_index ( ) const

Returns:
The material index that uniquely identifies the material associated to the geometry triangle.

© 2022, esss - all rights reserved

ROCKY api : solver manual 141

6.20.3.8 get_normal_unit_vector()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangle::get_normal_unit_vector ( ) const

Returns:
A unit vector in the normal direction to the geometry triangle, in Cartesian coordinates. The
orientation of this vector is arbitrary, since collision with particles can potentially happen on either
side of the geometry triangle.

6.20.3.9 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyGeometryTriangle::get_poisson_ratio ( ) const

Returns:
The triangle's Poisson's ratio. If this property was defined as variable for triangles in the module's
specification file, this method will return the value set specifically for the geometry triangle.
Otherwise, the returned value will be the one specified for the triangle's material in the Rocky UI.

6.20.3.10 get_scalars()

ROCKY_FUNCTIONS IRockyTriangleScalars IRockyGeometryTriangle::get_scalars ( )

Returns:
A IRockyTriangleScalars object that gives access to all triangle scalars variables defined in the
project.

6.20.3.11 get_temperature()

ROCKY_FUNCTIONS double IRockyGeometryTriangle::get_temperature ( ) const

Returns:
The temperature associated to the triangle. If that temperature was defined as a variable property
in the module's specification file, each triangle in a geometry may have a different temperature
value, set by a module using the IRockyGeometryTriangle::set_temperature method. Otherwise,
this method will return the temperature value specified in the UI for the geometry to which the
geometry triangle belongs.

6.20.3.12 get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyGeometryTriangle::get_thermal_conductivity ( ) const

Returns:
The triangle's thermal conductivity. If this property was defined as variable for triangles in the
module's specification file, this method will return the value set specifically for the geometry
triangle. Otherwise, the returned value will be the one specified for the triangle's material in the
Rocky UI.

6.20.3.13 get_translational_velocity()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangle::get_translational_velocity ( double current←-

_time ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 142

Parameters:
current_time The current value of the simulation time.

Returns:
The instantaneous triangle's translational velocity vector, expressed in Cartesian coordinates.

6.20.3.14 is_adiabatic()

ROCKY_FUNCTIONS bool IRockyGeometryTriangle::is_adiabatic ( ) const

Returns:
True if the geometry to which the boundary triangle belongs is adiabatic (i.e. it is not enabled to
exchange heat with particles).

6.20.3.15 set_poisson_ratio()

ROCKY_FUNCTIONS void IRockyGeometryTriangle::set_poisson_ratio ( double value )

This method sets the triangle's Poisson's ratio, if this property was defined as
variable in the module's specification file. If this method is used otherwise, a
segmentation fault will occur.

Parameters:
value The Poisson's ratio to be set.

6.20.3.16 set_temperature()

ROCKY_FUNCTIONS void IRockyGeometryTriangle::set_temperature ( double value )

This method can be used only if the temperature was defined as a variable property
for geometry triangles in the module's specification file. A segmentation fault will
occur if this method is used otherwise. The temperature value specified with this
method will be used by Rocky when solving the thermal balance equations for the
particles in contact with the geometry triangle.

Parameters:
value The temperature value to be assigned to the geometry triangle.

6.20.3.17 set_thermal_conductivity()

ROCKY_FUNCTIONS void IRockyGeometryTriangle::set_thermal_conductivity ( double value )

This method sets the triangle's thermal conductivity, if this property was defined
as variable in the module's specification file. If this method is used otherwise, a
segmentation fault will occur.

Parameters:
value The thermal conductivity to be set.

© 2022, esss - all rights reserved

ROCKY api : solver manual 143

6.21 IRockyGeometryTriangleHost struct reference

#include <rocky_boundary_api.hpp>

6.21.1 Public member functions

 ROCKY_FUNCTIONS IRockyMaterial get_material () const
 ROCKY_FUNCTIONS double3 get_normal_unit_vector () const
 ROCKY_FUNCTIONS double get_area () const
 ROCKY_FUNCTIONS double3 get_centroid () const
 ROCKY_FUNCTIONS int get_geometry_index () const
 ROCKY_FUNCTIONS int get_material_index () const
 ROCKY_FUNCTIONS double3 get_translational_velocity (double current_time) const
 ROCKY_FUNCTIONS double3 get_geometry_rotational_velocity () const
 ROCKY_FUNCTIONS double3 get_geometry_rotation_center () const
 ROCKY_FUNCTIONS double get_temperature () const
 ROCKY_FUNCTIONS void set_temperature (double value)
 ROCKY_FUNCTIONS bool is_adiabatic () const
 ROCKY_FUNCTIONS double get_thermal_conductivity () const
 ROCKY_FUNCTIONS void set_thermal_conductivity (double value)
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS void set_poisson_ratio (double value)
 ROCKY_FUNCTIONS IRockyTriangleScalars get_scalars ()

6.21.2 Detailed description

IRockyGeometryTriangleHost is the counterpart of IRockyGeometryTriangleHost

intended to be used during initialization operations, which is always performed on
CPU. Both of them share the same methods.

6.21.3 Member function documentation

6.21.3.1 get_area()

ROCKY_FUNCTIONS double IRockyGeometryTriangleHost::get_area ( ) const

Returns:
The unsigned area of the geometry triangle.

6.21.3.2 get_centroid()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangleHost::get_centroid ( ) const

Returns:
The centroid point of the geometry triangle in Cartesian coordinates.

© 2022, esss - all rights reserved

ROCKY api : solver manual 144

6.21.3.3 get_geometry_index()

ROCKY_FUNCTIONS int IRockyGeometryTriangleHost::get_geometry_index ( ) const

Returns:
The index that uniquely identifies the geometry to which the geometry triangle belongs.

6.21.3.4 get_geometry_rotation_center()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangleHost::get_geometry_rotation_center ( ) const

Returns:
The Cartesian coordinates of the rotation center of the motion frame attached to the geometry to
which the triangle belongs.

6.21.3.5 get_geometry_rotational_velocity()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangleHost::get_geometry_rotational_velocity ( ) const

Returns:
The rotational velocity vector of the geometry to which the triangle belongs, expressed in Cartesian
coordinates.

6.21.3.6 get_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyGeometryTriangleHost::get_material ( ) const

Returns:
An IRockyMaterial object that gives access to the values of physical properties associated to the
material from which the geometry triangle is made.

6.21.3.7 get_material_index()

ROCKY_FUNCTIONS int IRockyGeometryTriangleHost::get_material_index ( ) const

Returns:
The material index that uniquely identifies the material associated to the geometry triangle.

6.21.3.8 get_normal_unit_vector()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangleHost::get_normal_unit_vector ( ) const

Returns:
A unit vector in the normal direction to the geometry triangle, in Cartesian coordinates. The
orientation of this vector is arbitrary, since collision with particles can potentially happen on either
side of the geometry triangle.

6.21.3.9 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyGeometryTriangleHost::get_poisson_ratio ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 145

Returns:
The triangle's Poisson's ratio. If this property was defined as variable for triangles in the module's
specification file, this method will return the value set specifically for the geometry triangle.
Otherwise, the returned value will be the one specified for the triangle's material in the Rocky UI.

6.21.3.10 get_scalars()

ROCKY_FUNCTIONS IRockyTriangleScalars IRockyGeometryTriangleHost::get_scalars ( )

Returns:
A IRockyTriangleScalars object that gives access to all triangle scalars variables defined in the
project.

6.21.3.11 get_temperature()

ROCKY_FUNCTIONS double IRockyGeometryTriangleHost::get_temperature ( ) const

Returns:
The temperature associated to the triangle. If that temperature was defined as a variable property
in the module's specification file, each triangle in a geometry may have a different temperature
value, set by a module using the IRockyGeometryTriangle::set_temperature method. Otherwise,
this method will return the temperature value specified in the UI for the geometry to which the
geometry triangle belongs.

6.21.3.12 get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyGeometryTriangleHost::get_thermal_conductivity ( ) const

Returns:
The triangle's thermal conductivity. If this property was defined as variable for triangles in the
module's specification file, this method will return the value set specifically for the geometry
triangle. Otherwise, the returned value will be the one specified for the triangle's material in the
Rocky UI.

6.21.3.13 get_translational_velocity()

ROCKY_FUNCTIONS double3 IRockyGeometryTriangleHost::get_translational_velocity ( double current←-

_time ) const

Parameters:

current_time The current value of the simulation time.

Returns:
The instantaneous triangle's translational velocity vector, expressed in Cartesian coordinates.

© 2022, esss - all rights reserved

ROCKY api : solver manual 146

6.21.3.14 is_adiabatic()

ROCKY_FUNCTIONS bool IRockyGeometryTriangleHost::is_adiabatic ( ) const

Returns:
True if the geometry to which the boundary triangle belongs is adiabatic (i.e. it is not enabled to
exchange heat with particles).

6.21.3.15 set_poisson_ratio()

ROCKY_FUNCTIONS void IRockyGeometryTriangleHost::set_poisson_ratio ( double value )

This method sets the triangle's Poisson's ratio, if this property was defined as
variable in the module's specification file. If this method is used otherwise, a
segmentation fault will occur.

Parameters:
value The Poisson's ratio to be set.

6.21.3.16 set_temperature()

ROCKY_FUNCTIONS void IRockyGeometryTriangleHost::set_temperature ( double value )

This method can be used only if the temperature was defined as a variable property
for geometry triangles in the module's specification file. A segmentation fault will
occur if this method is used otherwise. The temperature value specified with this
method will be used by Rocky when solving the thermal balance equations for the
particles in contact with the geometry triangle.

Parameters:
value The temperature value to be assigned to the geometry triangle.

6.21.3.17 set_thermal_conductivity()

ROCKY_FUNCTIONS void IRockyGeometryTriangleHost::set_thermal_conductivity ( double value )

This method sets the triangle's thermal conductivity, if this property was defined
as variable in the module's specification file. If this method is used otherwise, a
segmentation fault will occur.

Parameters:
value The thermal conductivity to be set.

6.22 IRockyJoint struct reference

#include <rocky_joint_api.hpp>

© 2022, esss - all rights reserved

ROCKY api : solver manual 147

6.22.1 Public member functions

 ROCKY_FUNCTIONS double3 get_elastic_force () const
 ROCKY_FUNCTIONS thrust::tuple< double3, double3 > get_moments_due_to_force (double3 force) const
 ROCKY_FUNCTIONS double3 get_elastic_moment () const
 ROCKY_FUNCTIONS double3 get_damping_force () const
 ROCKY_FUNCTIONS double3 get_damping_moment () const
 ROCKY_FUNCTIONS double3 get_normal_deformation () const
 ROCKY_FUNCTIONS double3 get_tangential_deformation () const
 ROCKY_FUNCTIONS double3 get_normal_deformation_velocity () const
 ROCKY_FUNCTIONS double3 get_tangential_deformation_velocity () const
 ROCKY_FUNCTIONS int get_number_angular_deformations () const
 ROCKY_FUNCTIONS double get_angular_deformation (int deformation_direction) const
 ROCKY_FUNCTIONS double get_angular_deformation_velocity (int deformation_direction) const
 ROCKY_FUNCTIONS double3 get_angular_deformation_direction (int deformation_direction) const
 ROCKY_FUNCTIONS double get_normal_stiffness () const
 ROCKY_FUNCTIONS double get_tangential_stiffness () const
 ROCKY_FUNCTIONS double get_angular_stiffness (int deformation_direction) const
 ROCKY_FUNCTIONS double get_normal_damping_coefficient () const
 ROCKY_FUNCTIONS double get_tangential_damping_coefficient () const
 ROCKY_FUNCTIONS double get_angular_damping_coefficient (int deformation_direction) const
 ROCKY_FUNCTIONS double3 get_normal_vector () const
 ROCKY_FUNCTIONS double get_area () const
 ROCKY_FUNCTIONS double get_area_moment_of_inertia (int deformation_direction) const
 ROCKY_FUNCTIONS double get_young_modulus () const
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS double get_normal_elastic_ratio () const
 ROCKY_FUNCTIONS double get_tangential_elastic_ratio () const
 ROCKY_FUNCTIONS double get_torsion_elastic_ratio () const
 ROCKY_FUNCTIONS double get_bending_elastic_ratio () const
 ROCKY_FUNCTIONS double get_angle_scaling_factor () const
 ROCKY_FUNCTIONS double get_young_modulus_multiplier () const
 ROCKY_FUNCTIONS IRockyJointScalars get_scalars ()
 ROCKY_FUNCTIONS thrust::tuple< double3, double > get_home_element_orientation () const
 ROCKY_FUNCTIONS thrust::tuple< double3, double > get_near_element_orientation () const
 ROCKY_FUNCTIONS double3 get_home_element_centroid_position () const
 ROCKY_FUNCTIONS double3 get_near_element_centroid_position () const
 ROCKY_FUNCTIONS double3 get_home_arm () const
 ROCKY_FUNCTIONS double3 get_near_arm () const

© 2022, esss - all rights reserved

ROCKY api : solver manual 148

6.22.2 Detailed description

IRockyJoint is an interface for the internal joint object in Rocky. It contains

methods that give access to joint physical properties and geometric data, in order to
implement a custom model for the response of a joint to deformations. All property
and variable values made available through IRockyJoint are dimensionless.
When it is necessary to distinguish between the two elements linked by a joint,
one is referred to as home element, whereas the other is referred to as near element.
The local coordinate framework associated to a joint has the normal unit vector
always pointing from the home element to the near element. Whenever the name of
a method or object associated to a joint includes the prefix home or near, that means
the method or object is related to the home or near element.

6.22.3 Member function documentation

6.22.3.1 get_angle_scaling_factor()

ROCKY_FUNCTIONS double IRockyJoint::get_angle_scaling_factor ( ) const

When the number of elements making up a flexible particle is increased, the bending
deformation angles tend to decrease, for the same configuration of external forces
acting on the particle. This is a side effect of the discretized representation of a
flexible particle. In order to prevent the abnormal influence of this phenomenon on
models that have a bending angle as a parameter (for instance a threshold angle for
the change of regime), that angle can be multiplied by the scaling factor provided by
this function. This scaling factor is defined as the inverse of the number of elements
of the particle, when it is a fiber. For shells, it is defined as the inverse of the square
root of the number of elements.

Returns:
The angle scaling factor defined above.

6.22.3.2 get_angular_damping_coefficient()

ROCKY_FUNCTIONS double IRockyJoint::get_angular_damping_coefficient ( int deformation_direction

) const

Calculates the damping coefficient for computing a viscous moment in one of the
three orthogonal local directions.

Parameters:
deformation_direction An integer index that identifies the deformation direction. The three
possible values for this parameter are: 0 – torsion, 1 – first bending
direction, 2 – second bending direction.

© 2022, esss - all rights reserved

ROCKY api : solver manual 149

Returns:
A damping coefficient calculated with one of the following equations of the DEM Technical
Manual: equation 3.25 if deformation_direction = 0, equation 3.26 if deformation_direction = 1, or
equation 3.27 if deformation_direction = 2.

6.22.3.3 get_angular_deformation()

ROCKY_FUNCTIONS double IRockyJoint::get_angular_deformation ( int deformation_direction ) const

Calculates the angular deformation of the joint in one of the possible three mutually
orthogonal directions. Figure 3.7 of the DEM Technical Manual illustrates those
angles and directions for the shell case.

Parameters:

deformation_direction An integer index that identifies the deformation direction. The three
possible values for this parameter are: 0 – torsion direction, 1 – first
bending direction, 2 – second bending direction.

Returns:
The value of the angle for the given direction.

6.22.3.4 get_angular_deformation_direction()

ROCKY_FUNCTIONS double3 IRockyJoint::get_angular_deformation_direction ( int deformation←-

_direction ) const

Returns the unit vector in one of the three mutually orthogonal directions that
define the joint local framework.

Parameters:

deformation_direction An integer index that identifies the deformation direction. The three
possible values for this parameter are: 0 – torsion, 1 – first bending
direction, 2 – second bending direction.

Returns:
The unit vector in Cartesian coordinates associated to for the given direction.

6.22.3.5 get_angular_deformation_velocity()

ROCKY_FUNCTIONS double IRockyJoint::get_angular_deformation_velocity ( int deformation_direction

) const

Calculates the angular deformation velocity of the joint in one of the possible three
mutually orthogonal directions.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 150

deformation_direction An integer index that identifies the deformation direction. The three
possible values for this parameter are: 0 – torsion, 1 – first bending
direction, 2 – second bending direction.

Returns:
The magnitude of the angular deformation velocity for the given direction.

6.22.3.6 get_angular_stiffness()

ROCKY_FUNCTIONS double IRockyJoint::get_angular_stiffness ( int deformation_direction ) const

Calculates the stiffness value for computing a joint moment in one of the three
orthogonal local directions, according to the linear elastic model. This stiffness can
be used as a reference stiffness value for calculating a joint moment with a custom
joint model.

Parameters:
deformation_direction An integer index that identifies the deformation direction. The three
possible values for this parameter are: 0 – torsion, 1 – first bending
direction, 2 – second bending direction.

Returns:
A stiffness value calculated with one of the following equations of the DEM Technical Manual:
equation 3.10 if deformation_direction = 0, equation 3.11 if deformation_direction = 1, or equation
3.12 if deformation_direction = 2.

6.22.3.7 get_area()

ROCKY_FUNCTIONS double IRockyJoint::get_area ( ) const

Returns:
The cross sectional area associated to the joint. For fibers, it will be the area of the circular section of
the element with smaller diameter between the two connected by the joint. For shells, it will be the
area of the rectangle whose dimensions are the shell thickness and the length of the corresponding
triangle's edge. For polyhedra, it will be the area of the triangular face common to the two
tetrahedral elements connected by the joint.

6.22.3.8 get_area_moment_of_inertia()

ROCKY_FUNCTIONS double IRockyJoint::get_area_moment_of_inertia ( int deformation_direction

) const

Parameters:
deformation_direction An integer index that identifies the deformation direction. The three
possible values for this parameter are: 0 – torsion, 1 – first bending
direction, 2 – second bending direction.

Returns:
The area moment of inertia of the cross section of the joint associated to deformation_direction. If
deformation_direction = 0, the polar area moment of inertia is returned.

© 2022, esss - all rights reserved

ROCKY api : solver manual 151

6.22.3.9 get_bending_elastic_ratio()

ROCKY_FUNCTIONS double IRockyJoint::get_bending_elastic_ratio ( ) const

The bending elastic ratio is defined as the ratio between the Young's modulus
employed for calculating the stiffness for bending deformations to the Young's
modulus specified for the particle's material.

Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the
elastic ratio for bending deformations. Otherwise, it is assumed an isotropic behavior and it will
return the value specified for the only elastic ratio that appears in the Rocky UI.

6.22.3.10 get_damping_force()

ROCKY_FUNCTIONS double3 IRockyJoint::get_damping_force ( ) const

Calculates a viscous force proportional to the linear deformation velocity of the

joint. The addition of this force introduces a mechanism of energy dissipation that
may help to attenuate internal vibrations between elements in a flexible particle.
The force provided by this method is defined as positive in relation to the home
element, and negative in relation to the near element.

Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the forces defined in equations
3.18 and 3.19 of the DEM Technical Manual.

6.22.3.11 get_damping_moment()

ROCKY_FUNCTIONS double3 IRockyJoint::get_damping_moment ( ) const

Calculates a viscous moment proportional to the angular deformation velocity of the

joint. The addition of this moment introduces a mechanism of energy dissipation
that may help to attenuate internal angular oscillations between elements in a
flexible particle.

Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the moments defined in equations
3.20, 3.21 and 3.22 of the DEM Technical Manual. When the flexible particle is a fiber, equation 3.22
is disregarded because bending occurs in only one direction in that case. The moment provided by
this method is defined as positive in relation to the home element, and negative in relation to the
near element.

6.22.3.12 get_elastic_force()

ROCKY_FUNCTIONS double3 IRockyJoint::get_elastic_force ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 152

Calculates the resultant force according to the linear elastic model described in
section 3.2.1 of the DEM Technical Manual. This is useful when the custom module
is going to implement a new model only for joint moments, while using the standard
linear elastic model for the joint force. The force provided by this method is defined
as positive in relation to the home element, and negative in relation to the near
element.

Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the forces defined in equations 3.3
and 3.4 of the DEM Technical Manual.

6.22.3.13 get_elastic_moment()

ROCKY_FUNCTIONS double3 IRockyJoint::get_elastic_moment ( ) const

Calculates the resultant moment according to the linear elastic model described
in section 3.2.1 of the DEM Technical Manual. This is useful when the custom
module is going to implement a new model only for the joint forces, while using
the standard linear elastic model for the joint moments. The moment provided by
this method is defined as positive in relation to the home element, and negative in
relation to the near element.

Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the moments defined in equations
3.5, 3.6 and 3.7 of the DEM Technical Manual. When the flexible particle is a fiber, equation 3.7 is
disregarded, because only one bending moment exists in that case.

6.22.3.14 get_home_arm()

ROCKY_FUNCTIONS double3 IRockyJoint::get_home_arm ( ) const

Returns:
The vector that joins the home element center to the joint center.

6.22.3.15 get_home_element_centroid_position()

ROCKY_FUNCTIONS double3 IRockyJoint::get_home_element_centroid_position ( ) const

Returns:
The joint home element center point coordinates.

6.22.3.16 get_home_element_orientation()

ROCKY_FUNCTIONS thrust::tuple<double3, double> IRockyJoint::get_home_element_orientation (

) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 153

Returns:
A tuple whose two components define the axis-angle home element orientation. The first one
is a three dimensional vector representing the orientation axis, the second one is a single value
representing the angle.

6.22.3.17 get_moments_due_to_force()

ROCKY_FUNCTIONS thrust::tuple<double3, double3> IRockyJoint::get_moments_due_to_force ( double3

force ) const

Calculates the moments of the joint force on the two linked elements. As the lever
arm of the joint force can be different for the two elements, the corresponding
moment on each one of them can have different magnitude. This method must be
called always after calculating the joint force.

Parameters:

force The joint force as a vector in Cartesian coordinates.

Returns:
A tuple of two vectors in Cartesian coordinates, the first one is the moment on the home element,
the second one is the moment on the near element.

6.22.3.18 get_near_arm()

ROCKY_FUNCTIONS double3 IRockyJoint::get_near_arm ( ) const

Returns:
The vector that joins the near element center to the joint center.

6.22.3.19 get_near_element_centroid_position()

ROCKY_FUNCTIONS double3 IRockyJoint::get_near_element_centroid_position ( ) const

Returns:
The joint near element center point coordinates.

6.22.3.20 get_near_element_orientation()

ROCKY_FUNCTIONS thrust::tuple<double3, double> IRockyJoint::get_near_element_orientation (

) const

Returns:
A tuple whose two components define the axis-angle near element orientation. The first one is
a three dimensional vector representing the orientation axis, the second one is a single value
representing the angle.

© 2022, esss - all rights reserved

ROCKY api : solver manual 154

6.22.3.21 get_normal_damping_coefficient()

ROCKY_FUNCTIONS double IRockyJoint::get_normal_damping_coefficient ( ) const

Calculates the damping coefficient for computing the normal component of the
viscous force.

Returns:
The damping coefficient calculated with equation 3.23 of the DEM Technical Manual.

6.22.3.22 get_normal_deformation()

ROCKY_FUNCTIONS double3 IRockyJoint::get_normal_deformation ( ) const

Calculates the normal component of the linear deformation of the joint. The joint
linear deformation is defined as the relative displacement vector between the joint
center points in the two linked elements (see figure 3.2 of the DEM Technical
Manual). This vector is oriented pointing from the home element to the near
element.

Returns:
A vector in Cartesian coordinates, calculated as the product of the magnitude given by equation 3.1
and the normal unit vector.

6.22.3.23 get_normal_deformation_velocity()

ROCKY_FUNCTIONS double3 IRockyJoint::get_normal_deformation_velocity ( ) const

Calculates the normal component of the linear deformation velocity of the joint.
This velocity is the time derivative of the relative displacement vector between the
center points associated to the joint in the two linked elements. The decomposition
of this vector into normal and tangential directions is analogous to the one depicted
in figure 3.3 of the DEM Technical Manual.

Returns:
The normal component of the linear deformation velocity, expressed in Cartesian coordinates.

6.22.3.24 get_normal_elastic_ratio()

ROCKY_FUNCTIONS double IRockyJoint::get_normal_elastic_ratio ( ) const

The normal elastic ratio is defined as the ratio between the Young's modulus
employed for calculating the stiffness in the normal direction to the Young's modulus
specified for the particle's material.

Returns:

© 2022, esss - all rights reserved

ROCKY api : solver manual 155

If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the
elastic ratio in the normal direction. Otherwise, it is assumed an isotropic behavior and it will
return the value specified for the only elastic ratio that appears in the Rocky UI.

6.22.3.25 get_normal_stiffness()

ROCKY_FUNCTIONS double IRockyJoint::get_normal_stiffness ( ) const

Calculates the stiffness value for computing the joint normal force according to the
linear elastic model. This stiffness can be used as a reference stiffness value for
calculating the joint normal force with a custom joint model.

Returns:
The stiffness value calculated with equation 3.8 of the DEM Technical Manual.

6.22.3.26 get_normal_vector()

ROCKY_FUNCTIONS double3 IRockyJoint::get_normal_vector ( ) const

Returns:
The unit normal vector associated to the joint. This vector is defined as indicated in Figure 3.2. It is
oriented pointing always to the home element.

6.22.3.27 get_number_angular_deformations()

ROCKY_FUNCTIONS int IRockyJoint::get_number_angular_deformations ( ) const

Returns:
An integer representing the number of possible angular deformations. For joints in a flexible fiber,
it will return 2 (torsion and bending), while for joints in the other particle types, it will return 3
(torsion and two bending directions).

6.22.3.28 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyJoint::get_poisson_ratio ( ) const

Returns:
The value of the Poisson's ratio specified in the Rocky UI for the material associated to the particle.
If Poisson's ratio is configured as a variable property (i.e. each particle have a Poisson's ratio value),
then the ratio is the average between home and near elements ratios.

6.22.3.29 get_scalars()

ROCKY_FUNCTIONS IRockyJointScalars IRockyJoint::get_scalars ( )

If a scalar variable was defined during the setup of the module, this method can
be used access such variables. Joint scalars are special variables that store custom
values per joint, in order to preserve them between time iterations.

Returns:
The class to manipulate joint's scalars

© 2022, esss - all rights reserved

ROCKY api : solver manual 156

6.22.3.30 get_tangential_damping_coefficient()

ROCKY_FUNCTIONS double IRockyJoint::get_tangential_damping_coefficient ( ) const

Calculates the damping coefficient for computing the tangential component of the
viscous force.

Returns:
The damping coefficient calculated with equation 3.24 of the DEM Technical Manual.

6.22.3.31 get_tangential_deformation()

ROCKY_FUNCTIONS double3 IRockyJoint::get_tangential_deformation ( ) const

Calculates the tangential component of the linear deformation of the joint. The
joint linear deformation is defined as the relative displacement vector between the
joint center points in the two linked elements (see figure 3.2 of the DEM Technical
Manual).

Returns:
A vector in Cartesian coordinates, given by equation 3.2 of the DEM Technical Manual.

6.22.3.32 get_tangential_deformation_velocity()

ROCKY_FUNCTIONS double3 IRockyJoint::get_tangential_deformation_velocity ( ) const

Calculates the tangential component of the linear deformation velocity of the joint.
This velocity is the time derivative of the relative displacement vector between the
center points associated to the joint in the two linked elements. The decomposition
of this vector into normal and tangential directions is analogous to the one depicted
in figure 3.3 of the DEM Technical Manual.

Returns:
The tangential component of the linear deformation velocity, expressed in Cartesian coordinates.

6.22.3.33 get_tangential_elastic_ratio()

ROCKY_FUNCTIONS double IRockyJoint::get_tangential_elastic_ratio ( ) const

The tangential elastic ratio is defined as the ratio between the Young's modulus
employed for calculating the stiffness in the tangential direction to the Young's
modulus specified for the particle's material.

Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the
elastic ratio in the tangential direction. Otherwise, it is assumed an isotropic behavior and it will
return the value specified for the only elastic ratio that appears in the Rocky UI.

© 2022, esss - all rights reserved

ROCKY api : solver manual 157

6.22.3.34 get_tangential_stiffness()

ROCKY_FUNCTIONS double IRockyJoint::get_tangential_stiffness ( ) const

Calculates the stiffness value for computing the joint tangential force according to
the linear elastic model. This stiffness can be used as a reference stiffness value for
calculating the joint tangential force with a custom joint model.

Returns:
The stiffness value calculated with equation 3.9 of the DEM Technical Manual.

6.22.3.35 get_torsion_elastic_ratio()

ROCKY_FUNCTIONS double IRockyJoint::get_torsion_elastic_ratio ( ) const

The torsion elastic ratio is defined as the ratio between the Young's modulus
employed for calculating the stiffness for torsional deformations to the Young's
modulus specified for the particle's material.

Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the
elastic ratio for torsional deformations. Otherwise, it is assumed an isotropic behavior and it will
return the value specified for the only elastic ratio that appears in the Rocky UI.

6.22.3.36 get_young_modulus()

ROCKY_FUNCTIONS double IRockyJoint::get_young_modulus ( ) const

Returns:
The value of the Young's modulus specified in the Rocky UI for the material associated to the
particle.

6.22.3.37 get_young_modulus_multiplier()

ROCKY_FUNCTIONS double IRockyJoint::get_young_modulus_multiplier ( ) const

Returns:
For custom fibers only, this will return the factor in the right-hand side of equation 3.15 in the DEM
Technical Manual. For any other particle type, it will return 1.

6.23 IRockyJointScalars struct reference

#include <rocky_joint_scalars.hpp>

6.23.1 Public member functions

 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 158

 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const

 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.23.2 Detailed description

When running a simulation an IRockyJointScalars object gives access to all joint

scalars defined in the project. These joint scalars can be built-in scalars defined in
the solver, or custom joint scalars defined by the current module or other active
modules.

6.23.3 Member function documentation

6.23.3.1 add_scalar()

ROCKY_FUNCTIONS void IRockyJointScalars::add_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.23.3.2 get_scalar()

ROCKY_FUNCTIONS double IRockyJointScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

6.23.3.3 max_scalar()

ROCKY_FUNCTIONS void IRockyJointScalars::max_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common

© 2022, esss - all rights reserved

ROCKY api : solver manual 159

use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.23.3.4 set_scalar()

ROCKY_FUNCTIONS void IRockyJointScalars::set_scalar ( int scalar_index, double value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.24 IRockyJointScalarsModel struct reference

#include <rocky_joint_scalars.hpp>

6.24.1 Public member functions

 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)

6.24.2 Detailed description

IRockyJointScalarsModel allows users to add new joint scalars, find joint scalars
created in other modules or activate joint scalars known to Rocky, during the setup
phase of a module. Joint scalars are special variables attached to the joints of flexible
multi-element particles, which are able to store values per joint that are preserved
between time iterations during a simulation.

6.24.3 Member function documentation

© 2022, esss - all rights reserved

ROCKY api : solver manual 160

6.24.3.1 add()

int IRockyJointScalarsModel::add ( const char ∗ name, const char ∗ unit, bool output = true
)

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:
name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.24.3.2 find()

int IRockyJointScalarsModel::find ( const char ∗ name )

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:
name The name given to the scalar at the moment of its creation.

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

6.24.3.3 reset()

void IRockyJointScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.

6.24.3.4 set_dimension()

void IRockyJointScalarsModel::set_dimension ( int scalar_index, double dimension_factor )

© 2022, esss - all rights reserved

ROCKY api : solver manual 161

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:
scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

6.25 IRockyMaterial struct reference

#include <rocky_material_api.hpp>

6.25.1 Public member functions

 ROCKY_FUNCTIONS double get_young_modulus () const
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS double get_density () const
 ROCKY_FUNCTIONS double get_specific_heat () const
 ROCKY_FUNCTIONS double get_thermal_conductivity () const

6.25.2 Detailed description

IRockyMaterial is an interface for the internal material object, which gives access
to values of the physical properties associated to the material that makes up some
entity in Rocky. The values of all those properties are dimensionless values.

6.25.3 Member function documentation

6.25.3.1 get_density()

ROCKY_FUNCTIONS double IRockyMaterial::get_density ( ) const

Returns:
The value of the density of the material.

6.25.3.2 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyMaterial::get_poisson_ratio ( ) const

Returns:
The value of the Poisson's ratio specified for the material.

© 2022, esss - all rights reserved

ROCKY api : solver manual 162

6.25.3.3 get_specific_heat()

ROCKY_FUNCTIONS double IRockyMaterial::get_specific_heat ( ) const

Returns:
The value of the specific heat of the material.

6.25.3.4 get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyMaterial::get_thermal_conductivity ( ) const

Returns:
The value of the thermal conductivity of the material.

6.25.3.5 get_young_modulus()

ROCKY_FUNCTIONS double IRockyMaterial::get_young_modulus ( ) const

Returns:
The value of the Young's or elastic modulus. This value is the product of the Young's modulus
specified for the material and the numerical softening factor, which is commonly used for reducing
the stiffness and, in turn, increasing the simulation timestep. For more details, please refer to
section 5.2.4 of the DEM Technical Manual.

6.26 IRockyMaterialInteraction struct reference

#include <rocky_material_api.hpp>

6.26.1 Public member functions

 ROCKY_FUNCTIONS double get_restitution_coefficient () const
 ROCKY_FUNCTIONS double get_minimum_restitution_coefficient () const
 ROCKY_FUNCTIONS double get_static_friction_coefficient () const
 ROCKY_FUNCTIONS double get_dynamic_friction_coefficient () const
 ROCKY_FUNCTIONS double get_stiffness_multiplier () const
 ROCKY_FUNCTIONS double get_tangential_stiffness_ratio () const

6.26.2 Detailed description

IRockyMaterialInteraction is an interface for the internal material interaction

object, which gives access to values of the physical properties associated to contacts
involving combinations of two materials. The values of all those properties are
dimensionless values.

© 2022, esss - all rights reserved

ROCKY api : solver manual 163

6.26.3 Member function documentation

6.26.3.1 get_dynamic_friction_coefficient()

ROCKY_FUNCTIONS double IRockyMaterialInteraction::get_dynamic_friction_coefficient ( ) const

Returns:
The value of the dynamic coefficient of friction, which is used in tangential force models when
there exists tangential relative motion between two contacting entities.

6.26.3.2 get_minimum_restitution_coefficient()

ROCKY_FUNCTIONS double IRockyMaterialInteraction::get_minimum_restitution_coefficient ( ) const

Returns:
The value of the minimum restitution coefficient set by a module implementing a variable restitution
coefficient model. This value can be used to estimate the stable timestep for a custom contact model.
If the given project does not include a module that implements a variable restitution coefficient
model, the constant value specified through the Rocky UI will be returned.

6.26.3.3 get_restitution_coefficient()

ROCKY_FUNCTIONS double IRockyMaterialInteraction::get_restitution_coefficient ( ) const

Returns:
The value of the coefficient of restitution, which indirectly specifies the amount of energy dissipation
in a normal collision.

Attention:
The value returned by this function is always the one prescribed through the Rocky UI, therefore, it
is not affected by changes introduced by a module implementing a variable restitution coefficient
model.

6.26.3.4 get_static_friction_coefficient()

ROCKY_FUNCTIONS double IRockyMaterialInteraction::get_static_friction_coefficient ( ) const

Returns:
The value of the static coefficient of friction, which is used in tangential force models when there is
no tangential relative motion between two contacting entities.

6.26.3.5 get_stiffness_multiplier()

ROCKY_FUNCTIONS double IRockyMaterialInteraction::get_stiffness_multiplier ( ) const

Returns:
The value of the stiffness multiplier, which is used to increase the stiffness in collisions in order to
prevent large overlap values.

© 2022, esss - all rights reserved

ROCKY api : solver manual 164

6.26.3.6 get_tangential_stiffness_ratio()

ROCKY_FUNCTIONS double IRockyMaterialInteraction::get_tangential_stiffness_ratio ( ) const

Returns:
The value of the tangential stiffness ratio, which is used in tangential force models to relate the
tangential stiffness to the normal stiffness at a contact between two contacting entities.

6.27 IRockyModel struct reference

#include <rocky_api.h>

6.27.1 Public member functions

 double get_softening_factor () const
 bool is_thermal_simulation () const
 IRockyInteractionCalculationsData get_interactions_data () const
 void set_adhesive_distance (int home_index, int near_index, double adhesive_distance)
 void set_minimum_restitution_coefficient (int home_index, int near_index, double minimum_restitution)
 int get_number_of_particle_groups () const
 int get_number_of_particles () const
 int get_number_of_geometries () const
 int get_number_of_materials () const
 int get_number_of_material_interactions () const
 std::string get_geometry_name (int geometry_index) const
 std::string get_particle_group_name (int particle_group_index) const
 IRockyParticleScalarsModel get_particle_scalars () const
 IRockyParticleTransferScalarsModel get_particle_transfer_scalars () const
 IRockyParticleBreakageScalarsModel get_particle_breakage_scalars () const
 IRockyFluidScalarsModel get_fluid_scalars () const
 IRockyJointScalarsModel get_joint_scalars () const
 IRockyTriangleScalarsModel get_triangle_scalars () const
 IRockyContactScalarsModel get_particle_contact_scalars () const
 IRockyContactScalarsModel get_triangle_contact_scalars () const
 double get_current_time () const
 double get_output_interval () const
 int get_number_of_active_particles () const
 int get_number_of_active_triangles ()
 int get_number_of_processes () const
 int get_number_of_devices () const
 int get_device_id (int device_index) const
 int find_point_cloud (const std::string &point_cloud_name)
 int find_point_cloud_property (int point_cloud_index, const std::string &property_name)

© 2022, esss - all rights reserved

ROCKY api : solver manual 165

 void set_point_cloud_property_dimension (int point_cloud_index, int property_index, double dimension)

 IRockyCurveCollectionData get_curve_collections () const
 double get_length_factor () const
 double get_mass_factor () const
 double get_time_factor () const
 double get_temperature_factor () const
 double get_force_factor () const
 double get_pressure_factor () const
 double get_energy_factor () const
 ECFDCouplingMode get_coupling_mode () const

6.27.2 Detailed description

IRockyModel includes auxiliary functions for setting up a custom module. Most

of the preprocessing methods (such as ROCKY_PLUGIN_SETUP, ROCKY_PLUGIN←-
_INITIALIZE, ROCKY_PLUGIN_NON_DIMENSIONALIZE, etc) provide an IRockyModel

object as an argument.

6.27.3 Member function documentation

6.27.3.1 find_point_cloud()

int IRockyModel::find_point_cloud ( const std::string & point_cloud_name )

This method searches for a point cloud dataset in the project, by name.

Parameters:
name The name given to the point cloud in the Rocky UI.

Returns:
The index that uniquely identifies the wanted point cloud, if it was actually found. It returns -1
otherwise.

6.27.3.2 find_point_cloud_property()

int IRockyModel::find_point_cloud_property ( int point_cloud_index, const std::string & property←-

_name )

This method searches for a specific property name in a point cloud dataset imported
into Rocky.

Parameters:
point_cloud_index The index that uniquely identifies the point cloud.

name The name given to the property in the file defining the point cloud.

© 2022, esss - all rights reserved

ROCKY api : solver manual 166

Returns:
The index that uniquely identifies the wanted point cloud property, if it was actually found. It
returns -1 otherwise.

6.27.3.3 get_coupling_mode()

ECFDCouplingMode IRockyModel::get_coupling_mode ( ) const

Returns:
An ECFDCouplingMode enum which represents the CFD coupling mode. There are 5 coupling modes
in Rocky:
cfdcNone = 0
cfdcOneWay = 1
cfdcTwoWay = 2
cfdcOneWayConstant = 3
cfdcTwoWaySemiResolved = 4

6.27.3.4 get_current_time()

double IRockyModel::get_current_time ( ) const

Returns:
The value of the current simulation time.

6.27.3.5 get_curve_collections()

IRockyCurveCollectionData IRockyModel::get_curve_collections ( ) const

Returns:
An IRockyCurveCollectionData object that allows to create and manage custom time curves and/or
custom cross-plot curves that can be displayed in the Rocky UI.

6.27.3.6 get_device_id()

int IRockyModel::get_device_id ( int device_index ) const

Returns:
The index that identifies a given device when running a simulation in multi-GPU.

6.27.3.7 get_energy_factor()

double IRockyModel::get_energy_factor ( ) const

Returns:
The energy factor in Joule, used to nondimensionalize energy parameters.

6.27.3.8 get_fluid_scalars()

IRockyFluidScalarsModel IRockyModel::get_fluid_scalars ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 167

Returns:
A IRockyFluidScalarsModel object, that allows users to add new fluid scalars during a setup of
a module. Fluid scalars are special variables attached to CFD cell elements that are able to store
values that are preserved between time iterations.

6.27.3.9 get_force_factor()

double IRockyModel::get_force_factor ( ) const

Returns:
The force factor in Newton, used to nondimensionalize force parameters.

6.27.3.10 get_geometry_name()

std::string IRockyModel::get_geometry_name ( int geometry_index ) const

Returns:
The name given in the Rocky UI the geometry identified by geometry_index.

6.27.3.11 get_interactions_data()

IRockyInteractionCalculationsData IRockyModel::get_interactions_data ( ) const

Returns:
An IRockyInteractionCalculationsData object, which can be used to access data and methods related
to materials, materials interactions and particle groups.

6.27.3.12 get_joint_scalars()

IRockyJointScalarsModel IRockyModel::get_joint_scalars ( ) const

Returns:
A IRockyJointScalarsModel object, that allows users to add new joint scalars during a setup of a
module. Joint scalars are special variables attached to joints in flexible particles that are able to
store values that are preserved between time iterations.

6.27.3.13 get_length_factor()

double IRockyModel::get_length_factor ( ) const

Returns:
The length factor in meters, used to nondimensionalize length parameters.

6.27.3.14 get_mass_factor()

double IRockyModel::get_mass_factor ( ) const

Returns:
The length factor in kilograms, used to nondimensionalize mass parameters.

© 2022, esss - all rights reserved

ROCKY api : solver manual 168

6.27.3.15 get_number_of_active_particles()

int IRockyModel::get_number_of_active_particles ( ) const

Returns:
The current number of active particles in the simulation. This number can vary throughout a
simulation because new particles are injected and/or some particles leave the solution domain.

6.27.3.16 get_number_of_active_triangles()

int IRockyModel::get_number_of_active_triangles ( )

Returns:
The current number of active triangles in the simulation. This number can vary throughout a
simulation because the active particle region changes due to particles moving, which will active or
de-active triangles that are inside or outside the active region.

6.27.3.17 get_number_of_devices()

int IRockyModel::get_number_of_devices ( ) const

Returns:
The number of devices set to run the simulation when using multi-GPU.

6.27.3.18 get_number_of_geometries()

int IRockyModel::get_number_of_geometries ( ) const

Returns:
The total number of boundaries defined in the Rocky project.

6.27.3.19 get_number_of_material_interactions()

int IRockyModel::get_number_of_material_interactions ( ) const

Returns:
The total number of material interactions that it is possible to define with the current materials
defined in the Rocky project.

6.27.3.20 get_number_of_materials()

int IRockyModel::get_number_of_materials ( ) const

Returns:
The total number of materials defined in the Rocky project.

6.27.3.21 get_number_of_particle_groups()

int IRockyModel::get_number_of_particle_groups ( ) const

Returns:
The total number of particle groups defined in the Rocky project. A particle group is a category of
particles of the same shape and material.

© 2022, esss - all rights reserved

ROCKY api : solver manual 169

6.27.3.22 get_number_of_particles()

int IRockyModel::get_number_of_particles ( ) const

Returns:
The total number of individual particles in a whole simulation.

6.27.3.23 get_number_of_processes()

int IRockyModel::get_number_of_processes ( ) const

Returns:
The number of allowed parallel processes when the simulation runs in CPU.

6.27.3.24 get_output_interval()

double IRockyModel::get_output_interval ( ) const

Returns:
The value of the simulation output interval.

6.27.3.25 get_particle_breakage_scalars()

IRockyParticleBreakageScalarsModel IRockyModel::get_particle_breakage_scalars ( ) const

Returns:
An IRockyParticleBreakageScalarsModel object, that allows users to add new particle breakage
scalars or activate particle breakage scalars known to Rocky during the setup of a module. Particle
breakage scalars are special particle scalars used in conjunction with instantaneous breakage models,
in order to transfer values calculated at a breakage event to the point at which the fragments size
distribution is determined.

6.27.3.26 get_particle_contact_scalars()

IRockyContactScalarsModel IRockyModel::get_particle_contact_scalars ( ) const

Returns:
An IRockyContactScalarsModel object that allows users to add new (particle-to-particle) contact
scalars during the setup phase of a module. Contact scalars are special variables attached to
contacts that are able to store values that are preserved between time iterations.
For handling scalars related to particle-to-triangle contacts, please consult the
IRockyModel::get_triangle_contact_scalars method.

6.27.3.27 get_particle_group_name()

std::string IRockyModel::get_particle_group_name ( int particle_group_index ) const

Returns:
The name given in the Rocky UI the particle group identified by particle_group_index.

© 2022, esss - all rights reserved

ROCKY api : solver manual 170

6.27.3.28 get_particle_scalars()

IRockyParticleScalarsModel IRockyModel::get_particle_scalars ( ) const

Returns:
An IRockyParticleScalarsModel object, that allows users to add new particle scalars or activate
particle scalars known to Rocky during the setup of a module. Particle scalars are special variables
attached to particles that are able to store values per particle that are preserved between time
iterations.

6.27.3.29 get_particle_transfer_scalars()

IRockyParticleTransferScalarsModel IRockyModel::get_particle_transfer_scalars ( ) const

Returns:
An IRockyParticleTransferScalarsModel object, that allows users to add new particle transfer
scalars or activate particle transfer scalars known to Rocky during the setup of a module. Particle
transfer scalars are special particle scalars whose values are reset automatically to zero at the
beginning of a new time iteration. Their typical use is the accumulation of values from all contacts
or joints associated to a particle or an element at a given time iteration.

6.27.3.30 get_pressure_factor()

double IRockyModel::get_pressure_factor ( ) const

Returns:
The pressure factor in Pascal, used to nondimensionalize pressure parameters.

6.27.3.31 get_softening_factor()

double IRockyModel::get_softening_factor ( ) const

Returns:
The value of the numerical softening factor, which is a global reduction factor that multiplies all
stiffness values computed throughout a simulation. This factor is commonly used to increase the
timestep and, therefore, speed up the execution of simulations.

6.27.3.32 get_temperature_factor()

double IRockyModel::get_temperature_factor ( ) const

Returns:
The temperature factor in Kelvin, used to nondimensionalize temperature parameters.

6.27.3.33 get_time_factor()

double IRockyModel::get_time_factor ( ) const

Returns:
The time factor in seconds, used to nondimensionalize time parameters.

© 2022, esss - all rights reserved

ROCKY api : solver manual 171

6.27.3.34 get_triangle_contact_scalars()

IRockyContactScalarsModel IRockyModel::get_triangle_contact_scalars ( ) const

Returns:
An IRockyContactScalarsModel object that allows users to add new (particle-to-triangle) contact
scalars during the setup phase of a module. Contact scalars are special variables attached to
contacts that are able to store values that are preserved between time iterations.
For handling scalars for particle-to-particle contacts, please consult the
IRockyModel::get_particle_contact_scalars method.

6.27.3.35 get_triangle_scalars()

IRockyTriangleScalarsModel IRockyModel::get_triangle_scalars ( ) const

Returns:
A IRockyTriangleScalarsModel object, that allows users to add new triangle scalars during a setup
of a module. Triangle scalars are special variables attached to geometry triangles that are able to
store values that are preserved between time iterations.

6.27.3.36 is_thermal_simulation()

bool IRockyModel::is_thermal_simulation ( ) const

Returns:
True if thermal models are enabled in Rocky, false otherwise.

6.27.3.37 set_adhesive_distance()

void IRockyModel::set_adhesive_distance ( int home_index, int near_index, double adhesive←-

_distance )

This method sets a value of the adhesive distance per material interaction, for
a custom adhesive force model. Whenever a new value set for an adhesive
distance is greater than the previous maximum adhesive distance among all material
interactions, a new neighbors search operation will be triggered. For this reason, if
adhesive distances are increased too frequently, the simulation performance can be
compromised.

Parameters:
home_index The index of the first material in the material interaction.
near_index The index of the second material in the material interaction.
adhesive_distance The value of the adhesive distance for contacts involving entities with the
specified combination of materials.

6.27.3.38 set_minimum_restitution_coefficient()

void IRockyModel::set_minimum_restitution_coefficient ( int home_index, int near_index, double

minimum_restitution )

© 2022, esss - all rights reserved

ROCKY api : solver manual 172

This method is intended to be used by a module implementing a variable restitution

coefficient model. It allows the module to set the minimum expected value of the
restitution coefficient associated to a given material interaction. The Rocky solver
will use these values to calculate the stable timestep for the simulation. Every
time the value of the minimum restitution coefficient of any material interaction is
changed, a timestep calculation will be triggered. For this reason, if the restitution
coefficient changes too frequently, the simulation performance can be compromised.
The timestep will be changed only if the new calculated timestep is smaller than the
previous one.

Parameters:
home_index The index of the first material in the material interaction.
near_index The index of the second material in the material interaction.
minimum_restituion The minimum expected value for the restitution coefficient in a collision
involving entities with the specified combination of materials.

6.27.3.39 set_point_cloud_property_dimension()

void IRockyModel::set_point_cloud_property_dimension ( int point_cloud_index, int property←-

_index, double dimension )

The purpose of this method is to associate a dimensional factor to a point cloud

property. This factor will be used to nondimensionalize all the associated values.
For instance, if the property represents a force, a force dimensional factor must
be associated through this method. Dimensional factors for the fundamental
magnitudes are provided by functions of an IRockyModel object.

Parameters:
point_cloud_index The index that uniquely identifies the point cloud.

property_index The index that uniquely identifies the point cloud property.

dimension The appropriate dimensional factor for the point cloud property.

6.28 IRockyParticle struct reference

#include <rocky_particle_api.hpp>

6.28.1 Public member functions

 ROCKY_FUNCTIONS IRockyMaterial get_material () const
 ROCKY_FUNCTIONS double3 get_centroid_position () const
 ROCKY_FUNCTIONS double get_mass () const
 ROCKY_FUNCTIONS double get_original_mass () const
 ROCKY_FUNCTIONS double get_size () const

© 2022, esss - all rights reserved

ROCKY api : solver manual 173

 ROCKY_FUNCTIONS double get_release_time () const

 ROCKY_FUNCTIONS double get_cgm_scale_factor () const
 ROCKY_FUNCTIONS double get_volume () const
 ROCKY_FUNCTIONS double get_surface_area () const
 ROCKY_FUNCTIONS double get_equivalent_diameter () const
 ROCKY_FUNCTIONS double get_sphericity () const
 ROCKY_FUNCTIONS double3 get_translational_velocity () const
 ROCKY_FUNCTIONS double3 get_rotational_velocity () const
 ROCKY_FUNCTIONS double get_impact_energy () const
 ROCKY_FUNCTIONS double get_strength () const
 ROCKY_FUNCTIONS double3 get_gravity () const
 ROCKY_FUNCTIONS int get_particle_group_index () const
 ROCKY_FUNCTIONS int get_material_index () const
 ROCKY_FUNCTIONS double get_rolling_resistance_coefficient () const
 ROCKY_FUNCTIONS thrust::tuple< double3, double > get_orientation_axis_angle () const
 ROCKY_FUNCTIONS double4 get_orientation_quaternion () const
 ROCKY_FUNCTIONS double get_thermal_conductivity () const
 ROCKY_FUNCTIONS void set_thermal_conductivity (double value)
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS void set_poisson_ratio (double value)
 ROCKY_FUNCTIONS double get_specific_heat () const
 ROCKY_FUNCTIONS void set_specific_heat (double value)
 ROCKY_FUNCTIONS IRockyParticleScalars get_scalars ()
 ROCKY_FUNCTIONS const IRockyParticleScalars get_scalars () const
 ROCKY_FUNCTIONS IRockyParticleTransferScalars get_transfer_scalars ()
 ROCKY_FUNCTIONS IRockyParticleBreakageScalars get_breakage_scalars ()
 ROCKY_FUNCTIONS void remove ()
 ROCKY_FUNCTIONS void add_force (const double3 &force)
 ROCKY_FUNCTIONS void add_moment (const double3 &moment)
 ROCKY_FUNCTIONS void set_frozen (bool frozen)
 ROCKY_FUNCTIONS void disable_related_particle_contacts ()
 ROCKY_FUNCTIONS void enable_related_particle_contacts ()
 ROCKY_FUNCTIONS void disable_related_triangle_contacts ()
 ROCKY_FUNCTIONS void enable_related_triangle_contacts ()

6.28.2 Detailed description

IRockyParticle is an interface for the internal particle object in Rocky. A particle

object is the code representation of an individual particle in a Rocky simulation. It
has several access methods to particle-related properties, as well as particle scalars,
which are special variables that store values per particle that are preserved between
time iterations. Values of particle scalars can be displayed in a 3D window as any
other built-in particle property in Rocky. All property and variable values made
available through IRockyParticle are dimensionless.

© 2022, esss - all rights reserved

ROCKY api : solver manual 174

6.28.3 Member function documentation

6.28.3.1 add_force()

ROCKY_FUNCTIONS void IRockyParticle::add_force ( const double3 & force )

This method sums a custom calculated force to the contact and body forces acting
on the particle.

Parameters:

force The custom force vector in Cartesian coordinates.

6.28.3.2 add_moment()

ROCKY_FUNCTIONS void IRockyParticle::add_moment ( const double3 & moment )

This method sums a custom calculated moment to the moments acting on the
particle.

Parameters:

moment The custom moment vector in Cartesian coordinates.

6.28.3.3 disable_related_particle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::disable_related_particle_contacts ( )

This method disables the detection of particle-to-particle contacts for the particle.

6.28.3.4 disable_related_triangle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::disable_related_triangle_contacts ( )

This method disables the detection of particle-to-triangle contacts for the particle.

6.28.3.5 enable_related_particle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::enable_related_particle_contacts ( )

This method enables the detection of particle-to-particle contacts for the particle.

6.28.3.6 enable_related_triangle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::enable_related_triangle_contacts ( )

This method enables the detection of particle-to-triangle contacts for the particle.

© 2022, esss - all rights reserved

ROCKY api : solver manual 175

6.28.3.7 get_breakage_scalars()

ROCKY_FUNCTIONS IRockyParticleBreakageScalars IRockyParticle::get_breakage_scalars ( )

Returns:
An IRockyParticleBreakageScalars object, that gives access to all particle breakage scalars
variables defined in the project.

6.28.3.8 get_centroid_position()

ROCKY_FUNCTIONS double3 IRockyParticle::get_centroid_position ( ) const

Returns:
The Cartesian coordinates of the current position of the particle's centroid.

6.28.3.9 get_cgm_scale_factor()

ROCKY_FUNCTIONS double IRockyParticle::get_cgm_scale_factor ( ) const

Returns:
The particle's Coarse-grain Modeling (CGM) scale factor.

6.28.3.10 get_equivalent_diameter()

ROCKY_FUNCTIONS double IRockyParticle::get_equivalent_diameter ( ) const

Returns:
The equivalent diameter of the particle, which is defined as the diameter of a sphere of volume
equal to the particle's volume.

6.28.3.11 get_gravity()

ROCKY_FUNCTIONS double3 IRockyParticle::get_gravity ( ) const

Returns:
The gravitational acceleration vector in Cartesian coordinates.

6.28.3.12 get_impact_energy()

ROCKY_FUNCTIONS double IRockyParticle::get_impact_energy ( ) const

Returns:
The sum of the impact energy registered in all active contacts on the surface of the particle until a
given time.

Attention:
This value will be available only if a instantaneous breakage model is enabled in the simulation.

© 2022, esss - all rights reserved

ROCKY api : solver manual 176

6.28.3.13 get_mass()

ROCKY_FUNCTIONS double IRockyParticle::get_mass ( ) const

Returns:
The current value of the particle's mass. This value will be different from the original particle's
mass only if the mass increment particle scalar is enabled in the simulation.

6.28.3.14 get_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyParticle::get_material ( ) const

Returns:
An IRockyMaterial object that gives access to the values of physical properties associated to the
material from which the particle is made.

6.28.3.15 get_material_index()

ROCKY_FUNCTIONS int IRockyParticle::get_material_index ( ) const

Returns:
The material index associated to that particle

6.28.3.16 get_orientation_axis_angle()

ROCKY_FUNCTIONS thrust::tuple< double3, double > IRockyParticle::get_orientation_axis_angle

( ) const

Returns:
A tuple whose two components define the axis-angle particle orientation. The first one is a three
dimensional vector representing the orientation axis, the second one is a single value representing
the angle.

6.28.3.17 get_orientation_quaternion()

ROCKY_FUNCTIONS double4 IRockyParticle::get_orientation_quaternion ( ) const

Returns:
The quaternion that represents the particle's orientation, expressed as a four-dimensional array
( qr , q i , q j , q k ).

6.28.3.18 get_original_mass()

ROCKY_FUNCTIONS double IRockyParticle::get_original_mass ( ) const

Returns:
The original value of the mass of a particle when it enters into the simulation.

© 2022, esss - all rights reserved

ROCKY api : solver manual 177

6.28.3.19 get_particle_group_index()

ROCKY_FUNCTIONS int IRockyParticle::get_particle_group_index ( ) const

Returns:
The index that uniquely identifies the particle group to which the particle belongs.

6.28.3.20 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyParticle::get_poisson_ratio ( ) const

Returns:
The particle's Poisson's ratio value. If this property was defined as variable in the module's
specification file, the method will return the value specifically assigned to the particle. Otherwise,
it will return the value specified in the Rocky UI for the particle's associated material.

6.28.3.21 get_release_time()

ROCKY_FUNCTIONS double IRockyParticle::get_release_time ( ) const

Returns:
The time at which the particle was released.

6.28.3.22 get_rolling_resistance_coefficient()

ROCKY_FUNCTIONS double IRockyParticle::get_rolling_resistance_coefficient ( ) const

Returns:
The particle's rolling resistance coefficient

6.28.3.23 get_rotational_velocity()

ROCKY_FUNCTIONS double3 IRockyParticle::get_rotational_velocity ( ) const

Returns:
The current particle's rotational velocity vector expressed in Cartesian coordinates.

6.28.3.24 get_scalars() [1/2]

ROCKY_FUNCTIONS IRockyParticleScalars IRockyParticle::get_scalars ( )

Returns:
An IRockyParticleScalars object, that gives access to all particle scalars variables defined in the
project.

6.28.3.25 get_scalars() [2/2]

ROCKY_FUNCTIONS const IRockyParticleScalars IRockyParticle::get_scalars ( ) const

Returns:
A const IRockyParticleScalars object, that gives access to all particle scalars variables defined in
the project.

© 2022, esss - all rights reserved

ROCKY api : solver manual 178

6.28.3.26 get_size()

ROCKY_FUNCTIONS double IRockyParticle::get_size ( ) const

Returns:
The current value of the particle's size.

6.28.3.27 get_specific_heat()

ROCKY_FUNCTIONS double IRockyParticle::get_specific_heat ( ) const

Returns:
The particle's specific heat value. If this property was defined as variable in the module's specification
file, the method will return the value specifically assigned to the particle. Otherwise, it will return
the value specified in the Rocky UI for the particle's associated material.

6.28.3.28 get_sphericity()

ROCKY_FUNCTIONS double IRockyParticle::get_sphericity ( ) const

Returns:
The particle's sphericity value, which is defined as the ratio of As to A p , where As is the surface
area of a sphere with the same volume as the particle, whereas A p is the surface area of the particle
itself. In general terms, the sphericity measures how closely the particle's actual shape resembles
the shape of a perfect sphere.

6.28.3.29 get_strength()

ROCKY_FUNCTIONS double IRockyParticle::get_strength ( ) const

Returns:
A random value between 0 and 1 assigned to a particle at the time of generation. This value can be
related to the breakage probability in a custom instantaneous breakage model.

6.28.3.30 get_surface_area()

ROCKY_FUNCTIONS double IRockyParticle::get_surface_area ( ) const

Returns:
The current value of the particle's surface area.

6.28.3.31 get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyParticle::get_thermal_conductivity ( ) const

Returns:
The particle's thermal conductivity. If this property was defined as variable in the module's
specification file, the method will return the value specifically assigned to the particle. Otherwise,
it will return the value specified in the Rocky UI for the particle's associated material.

© 2022, esss - all rights reserved

ROCKY api : solver manual 179

6.28.3.32 get_transfer_scalars()

ROCKY_FUNCTIONS IRockyParticleTransferScalars IRockyParticle::get_transfer_scalars ( )

Returns:
An IRockyParticleTransferScalars object, that gives access to all particle transfer scalars variables
defined in the project.

6.28.3.33 get_translational_velocity()

ROCKY_FUNCTIONS double3 IRockyParticle::get_translational_velocity ( ) const

Returns:
The current particle's translational velocity vector expressed in Cartesian coordinates.

6.28.3.34 get_volume()

ROCKY_FUNCTIONS double IRockyParticle::get_volume ( ) const

Returns:
The current value of the particle's volume.

6.28.3.35 remove()

ROCKY_FUNCTIONS void IRockyParticle::remove ( )

This method removes permanently the particle from the simulation.

6.28.3.36 set_frozen()

ROCKY_FUNCTIONS void IRockyParticle::set_frozen ( bool frozen )

This method sets the frozen state of a particle. When the frozen state of a particle
is set to true, the solution of the motion equations for this particle are skipped
afterwards.

Parameters:
frozen True if the particle should be frozen, false otherwise.

6.28.3.37 set_poisson_ratio()

ROCKY_FUNCTIONS void IRockyParticle::set_poisson_ratio ( double value )

This method sets the Poisson's ratio value for the particle. This operation will be
allowed only if Poisson's ratio was defined as a variable property for particles in the
module's specification file. Otherwise, a segmentation fault will occur.

Parameters:
value The Poisson's ratio to be set.

© 2022, esss - all rights reserved

ROCKY api : solver manual 180

6.28.3.38 set_specific_heat()

ROCKY_FUNCTIONS void IRockyParticle::set_specific_heat ( double value )

This method sets the specific heat value for the particle. This operation will be
allowed only if Poisson's ratio was defined as a variable property for particles in the
module's specification file. Otherwise, a segmentation fault will occur.

Parameters:
value The specific heat to be set.

6.28.3.39 set_thermal_conductivity()

ROCKY_FUNCTIONS void IRockyParticle::set_thermal_conductivity ( double value )

This method sets the thermal conductivity value for the particle. This operation
will be allowed only if thermal conductivity was defined as a variable property for
particles in the module's specification file. Otherwise, a segmentation fault will
occur.

Parameters:
value The thermal conductivity to be set.

6.29 IRockyParticleBreakageScalars struct reference

#include <rocky_particle_scalars.hpp>

6.29.1 Public member functions

 ROCKY_FUNCTIONS double get_t10 () const
 ROCKY_FUNCTIONS void set_t10 (const double value)
 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const
 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.29.2 Detailed description

When running a simulation, an IRockyParticleBreakageScalars gives access to

all particle breakage scalars defined in the project. Particle breakage scalars are
special particle scalars which can be used to transfer data from the point where
the instantaneous breakage criterion is evaluated (at the ROCKY_PLUGIN_COMPUTE_←-
INSTANTANEOUS_BREAKAGE hook) to the point where the fragment size distribution is
calculated (at the ROCKY_PLUGIN_COMPUTE_FRAGMENTS_SIZE_DISTRIBUTION hook).

© 2022, esss - all rights reserved

ROCKY api : solver manual 181

6.29.3 Member function documentation

6.29.3.1 add_scalar()

ROCKY_FUNCTIONS void IRockyParticleBreakageScalars::add_scalar ( int scalar_index, double

value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.29.3.2 get_scalar()

ROCKY_FUNCTIONS double IRockyParticleBreakageScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

6.29.3.3 get_t10()

ROCKY_FUNCTIONS double IRockyParticleBreakageScalars::get_t10 ( ) const

Returns:
The value of the t10 parameter set at an instantaneous breakage event. Please refer to section 2.4 of
the DEM Technical Manual for the definition of this parameter.

6.29.3.4 max_scalar()

ROCKY_FUNCTIONS void IRockyParticleBreakageScalars::max_scalar ( int scalar_index, double

value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common
use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 182

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.29.3.5 set_scalar()

ROCKY_FUNCTIONS void IRockyParticleBreakageScalars::set_scalar ( int scalar_index, double

value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.29.3.6 set_t10()

ROCKY_FUNCTIONS void IRockyParticleBreakageScalars::set_t10 ( const double value )

This method sets the value of the t10 parameter calculated at an instantaneous
breakage event. Please refer to section 2.4 of the DEM Technical Manual for the
definition of this parameter.

Parameters:
value The value of the t10 parameter just calculated.

6.30 IRockyParticleBreakageScalarsModel struct refer-

ence
#include <rocky_particle_scalars.hpp>

6.30.1 Public member functions

 void enable_t10 ()
 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)

6.30.2 Detailed description

An IRockyParticleBreakageScalarsModel allows users to add new particle break-

age scalars, find particle breakage scalars created in other modules or activate

© 2022, esss - all rights reserved

ROCKY api : solver manual 183

particle breakage scalars known to Rocky, during the setup stage of a module.
Particle breakage scalars are special particle scalars which can be used to transfer
data from the point where the instantaneous breakage criterion is evaluated (at
the ROCKY_PLUGIN_COMPUTE_INSTANTANEOUS_BREAKAGE hook) to the point where the
fragment size distribution is calculated (at the ROCKY_PLUGIN_COMPUTE_FRAGMENTS←-
_SIZE_DISTRIBUTION hook). A typical use is to store the value of the t10 parameter,

which is calculated at the moment a particle breaks and is used for calculating the
resulting fragment size distribution. However, users can employ these scalars to
store whichever parameter that links the breakage criterion with the fragment size
distribution in their models.

6.30.3 Member function documentation

6.30.3.1 add()

int IRockyParticleBreakageScalarsModel::add ( const char ∗ name, const char ∗ unit, bool

output = true )

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:
name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.30.3.2 enable_t10()

void IRockyParticleBreakageScalarsModel::enable_t10 ( )

Enables a scalar known to Rocky that stores the t10 parameter value. A custom
instantaneous breakage model that is intended to work along with built-in fragment
size distribution models in Rocky must enable and calculate this scalar variable.

6.30.3.3 find()

int IRockyParticleBreakageScalarsModel::find ( const char ∗ name )

© 2022, esss - all rights reserved

ROCKY api : solver manual 184

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:

name The name given to the scalar at the moment of its creation.

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

6.30.3.4 reset()

void IRockyParticleBreakageScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.

6.30.3.5 set_dimension()

void IRockyParticleBreakageScalarsModel::set_dimension ( int scalar_index, double dimension←-

_factor )

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

6.31 IRockyParticleCloudPoint struct reference

#include <rocky_point_cloud_api.hpp>

6.31.1 Public member functions

 ROCKY_FUNCTIONS double3 get_position ()
 ROCKY_FUNCTIONS double get_property (int property_index)

© 2022, esss - all rights reserved

ROCKY api : solver manual 185

6.31.2 Detailed description

IParticleCloudPoint is an interface to the data of the nearest point to a particle at

a given time.

6.31.3 Member function documentation

6.31.3.1 get_position()

ROCKY_FUNCTIONS double3 IRockyParticleCloudPoint::get_position ( )

Returns:
The Cartesian coordinates of the referred point in the cloud point.

6.31.3.2 get_property()

ROCKY_FUNCTIONS double IRockyParticleCloudPoint::get_property ( int property_index )

Returns:
The value of a property in the cloud point dataset, corresponding to the referred point in the point
cloud.

6.32 IRockyParticleHost struct reference

#include <rocky_particle_api.hpp>

6.32.1 Public member functions

 double get_original_volume () const
 int get_material_index () const
 double get_equivalent_diameter () const
 IRockyMaterial get_material () const
 double3 get_centroid_position () const
 double get_original_mass () const
 double get_size () const
 double get_release_time () const
 double get_cgm_scale_factor () const
 bool is_released () const
 IRockyParticleScalars get_scalars ()

© 2022, esss - all rights reserved

ROCKY api : solver manual 186

6.32.2 Detailed description

IRockyParticleHost is an interface for the internal particle object in Rocky. A

particle object is the code representation of an individual particle in a Rocky
simulation. It has several access methods to particle-related properties, as
well as particle scalars, which are special variables that store values per particle
that are preserved between time iterations. The main difference in relation to
IRockyParticle is that all IRockyParticleHost's property and variable values have
their original dimensions as defined within the project, and its data resides within
host memory (DRAM).

6.32.3 Member function documentation

6.32.3.1 get_centroid_position()

double3 IRockyParticleHost::get_centroid_position ( ) const

Returns:
The Cartesian coordinates of the current position of the particle's centroid.

6.32.3.2 get_cgm_scale_factor()

double IRockyParticleHost::get_cgm_scale_factor ( ) const

Returns:
The particle's Coarse-grain Modeling (CGM) scale factor.

6.32.3.3 get_equivalent_diameter()

double IRockyParticleHost::get_equivalent_diameter ( ) const

Returns:
The equivalent diameter of the particle, which is defined as the diameter of a sphere of volume
equal to the particle's volume.

6.32.3.4 get_material()

IRockyMaterial IRockyParticleHost::get_material ( ) const

Returns:
An IRockyMaterial object that gives access to the values of physical properties associated to the
material from which the particle is made.

6.32.3.5 get_material_index()

int IRockyParticleHost::get_material_index ( ) const

Returns:
The material index associated to that particle

© 2022, esss - all rights reserved

ROCKY api : solver manual 187

6.32.3.6 get_original_mass()

double IRockyParticleHost::get_original_mass ( ) const

Returns:
The original value of the particle's mass.

6.32.3.7 get_original_volume()

double IRockyParticleHost::get_original_volume ( ) const

Returns:
The original value of the particle's volume.

6.32.3.8 get_release_time()

double IRockyParticleHost::get_release_time ( ) const

Returns:
The time particle was released.

6.32.3.9 get_scalars()

IRockyParticleScalars IRockyParticleHost::get_scalars ( )

Returns:
An IRockyParticleScalars object, that gives access to all particle scalars variables defined in the
project.

6.32.3.10 get_size()

double IRockyParticleHost::get_size ( ) const

Returns:
The current value of the particle's size.

6.32.3.11 is_released()

bool IRockyParticleHost::is_released ( ) const

Returns:
A true value if the particle was released into the simulation domain, false otherwise.

6.33 IRockyParticleScalars struct reference

#include <rocky_particle_scalars.hpp>

© 2022, esss - all rights reserved

ROCKY api : solver manual 188

6.33.1 Public member functions

 ROCKY_FUNCTIONS double get_temperature () const
 ROCKY_FUNCTIONS double get_mass_increment () const
 ROCKY_FUNCTIONS double get_volume_increment () const
 ROCKY_FUNCTIONS void set_temperature (const double value)
 ROCKY_FUNCTIONS void set_mass_increment (const double value)
 ROCKY_FUNCTIONS void set_volume_increment (const double value)
 ROCKY_FUNCTIONS void add_temperature (const double value)
 ROCKY_FUNCTIONS void add_explicit_fluid_momentum (const double3 value)
 ROCKY_FUNCTIONS void add_implicit_fluid_momentum (const double value)
 ROCKY_FUNCTIONS void add_explicit_fluid_heat_transfer_rate (const double value)
 ROCKY_FUNCTIONS void add_implicit_fluid_heat_transfer_rate (const double value)
 ROCKY_FUNCTIONS void add_mass_increment (const double value)
 ROCKY_FUNCTIONS void add_volume_increment (const double value)
 ROCKY_FUNCTIONS double get_thermal_conductivity () const
 ROCKY_FUNCTIONS void set_thermal_conductivity (const double value)
 ROCKY_FUNCTIONS double get_specific_heat () const
 ROCKY_FUNCTIONS void set_specific_heat (const double value)
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS void set_poisson_ratio (const double value)
 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const
 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.33.2 Detailed description

When running a simulation, an IRockyParticleScalars gives access to all particle

scalars defined in the project. These particle scalars can be built-in scalars defined
in the Rocky solver, or custom particle scalars defined by the current module or
other active modules.

6.33.3 Member function documentation

6.33.3.1 add_explicit_fluid_heat_transfer_rate()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_explicit_fluid_heat_transfer_rate ( const double

value )

This method adds the particle's implicit contribution into the CFD thermal energy
equation associated to the cell where the particle centroid is located. This operation

© 2022, esss - all rights reserved

ROCKY api : solver manual 189

is valid only for thermal-enabled two-way DEM-CFD coupling (please refer to the
DEM-CFD Coupling Technical Manual for more details).

Parameters:

value The particle's explicit heat transfer rate contribution.

6.33.3.2 add_explicit_fluid_momentum()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_explicit_fluid_momentum ( const double3 value

This method adds the particle's explicit contribution into the CFD momentum
equation associated to the cell where the particle centroid is located. This operation is
valid only for two-way DEM-CFD coupling (please refer to the DEM-CFD Coupling
Technical Manual for more details).

Parameters:

value The particle's explicit momentum contribution.

6.33.3.3 add_implicit_fluid_heat_transfer_rate()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_implicit_fluid_heat_transfer_rate ( const double

value )

// This method adds the particle's implicit contribution into the CFD thermal energy
equation associated to the cell where the particle centroid is located. This operation
is valid only for thermal-enabled two-way DEM-CFD coupling (please refer to the
DEM-CFD Coupling Technical Manual for more details).

Parameters:

value The particle's implicit heat transfer rate contribution.

6.33.3.4 add_implicit_fluid_momentum()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_implicit_fluid_momentum ( const double value

This method adds the particle's implicit contribution into the CFD momentum
equation associated to the cell where the particle centroid is located. This operation is
valid only for two-way DEM-CFD coupling (please refer to the DEM-CFD Coupling
Technical Manual for more details).

Parameters:

value The coefficient associated to particle's implicit momentum contribution.

© 2022, esss - all rights reserved

ROCKY api : solver manual 190

6.33.3.5 add_mass_increment()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_mass_increment ( const double value )

This method sums a value to the current mass increment of the particle.

Parameters:

value The value summed to the mass increment.

6.33.3.6 add_scalar()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_scalar ( int scalar_index, double value )

const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.33.3.7 add_temperature()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_temperature ( const double value )

This method sums a value to the current temperature of the particle.

Parameters:
value The value summed to the temperature.

6.33.3.8 add_volume_increment()

ROCKY_FUNCTIONS void IRockyParticleScalars::add_volume_increment ( const double value )

This method sums a value to the current volume increment of the particle.

Parameters:

value The value summed to the volume increment.

6.33.3.9 get_mass_increment()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_mass_increment ( ) const

Returns:
The value of the mass increment of the particle in relation to the initial mass at the time of entrance.
Different physical processes can cause this mass increment. The mass increment is a built-in particle
scalar defined in the solver.

© 2022, esss - all rights reserved

ROCKY api : solver manual 191

6.33.3.10 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_poisson_ratio ( ) const

Returns:
The value of the Poisson's ratio assigned to the particle. The Rocky solver has a built-in particle
scalar that once enabled allow particles to have a variable Poisson's ratio, which overrides the
constant value specified for the particle's material.

6.33.3.11 get_scalar()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

6.33.3.12 get_specific_heat()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_specific_heat ( ) const

Returns:
The value of the specific heat of the particle. The Rocky solver has a built-in particle scalar that
once enabled allow particles to have a variable specific heat, which overrides the constant value
specified for the particle's material.

6.33.3.13 get_temperature()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_temperature ( ) const

Returns:
The value of the current particle's temperature. Temperature is a built-in particle scalar defined in
the solver, enabled whenever a thermal model is active in the project.

6.33.3.14 get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_thermal_conductivity ( ) const

Returns:
The value of the thermal conductivity of the particle. The Rocky solver has a built-in particle scalar
that once enabled allow particles to have a variable thermal conductivity, which overrides the
constant value specified for the particle's material.

© 2022, esss - all rights reserved

ROCKY api : solver manual 192

6.33.3.15 get_volume_increment()

ROCKY_FUNCTIONS double IRockyParticleScalars::get_volume_increment ( ) const

Returns:
The value of the volume increment of the particle in relation to the initial volume at the time of
entrance. Different physical processes can cause this volume increment. The volume increment is a
built-in particle scalar defined in the solver.

6.33.3.16 max_scalar()

ROCKY_FUNCTIONS void IRockyParticleScalars::max_scalar ( int scalar_index, double value )

const

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common
use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:

scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.33.3.17 set_mass_increment()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_mass_increment ( const double value )

This method sets the value of the mass increment of the particle in relation to the
initial mass at the time of entrance.

Parameters:

value The value of the mass increment.

6.33.3.18 set_poisson_ratio()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_poisson_ratio ( const double value )

This method sets the value of the Poisson's ratio for the associated particle, if the
corresponding built-in particle scalar was enabled. Otherwise, a segmentation fault
will occur.

Parameters:

value The value of the Poisson's ratio for the particle.

© 2022, esss - all rights reserved

ROCKY api : solver manual 193

6.33.3.19 set_scalar()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_scalar ( int scalar_index, double value )

const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.33.3.20 set_specific_heat()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_specific_heat ( const double value )

This method sets the value of the specific heat for the associated particle, if the
corresponding built-in particle scalar was enabled. Otherwise, a segmentation fault
will occur.

Parameters:
value The value of the particle's specific heat.

6.33.3.21 set_temperature()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_temperature ( const double value )

This method sets the value of the temperature of the particle.

Parameters:
value The value of the temperature.

6.33.3.22 set_thermal_conductivity()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_thermal_conductivity ( const double value )

This method sets the value of the thermal conductivity for the associated particle, if
the corresponding built-in particle scalar was enabled. Otherwise, a segmentation
fault will occur.

Parameters:
value The value of the particle's thermal conductivity.

6.33.3.23 set_volume_increment()

ROCKY_FUNCTIONS void IRockyParticleScalars::set_volume_increment ( const double value )

© 2022, esss - all rights reserved

ROCKY api : solver manual 194

This method sets the value of the volume increment of the particle in relation to the
initial volume at the time of entrance.

Parameters:

value The value of the volume increment.

6.34 IRockyParticleScalarsModel struct reference

#include <rocky_particle_scalars.hpp>

6.34.1 Public member functions

 void enable_mass_increment ()
 void enable_volume_increment ()
 void enable_variable_thermal_conductivity ()
 void enable_variable_poisson_ratio ()
 void enable_variable_specific_heat ()
 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)

6.34.2 Detailed description

An IRockyParticleScalarsModel allows users to add new particle scalars, find

particle scalars created in other modules or activate particle scalars known to Rocky,
during the setup stage of a module. Particle scalars are special variables attached to
particles, which are able to store values per particle that are preserved between time
iterations during a simulation.

6.34.3 Member function documentation

6.34.3.1 add()

int IRockyParticleScalarsModel::add ( const char ∗ name, const char ∗ unit, bool output =
true )

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 195

name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.34.3.2 enable_mass_increment()

void IRockyParticleScalarsModel::enable_mass_increment ( )

Enables a known-scalar that associates a mass increment value to each particle in

a simulation. When this scalar is enabled, the instantaneous mass of a particle is
equal to the original mass defined at the beginning of a simulation plus the value of
that mass increment.

6.34.3.3 enable_variable_poisson_ratio()

void IRockyParticleScalarsModel::enable_variable_poisson_ratio ( )

Enables a known-scalar defining Poisson's ratio value to each particle in a simulation.

When this scalar is enabled, the instantaneous Poisson's ratio is defined as a variable
property, with possibly a different value and used everywhere in the simulation,
instead of the constant value of particle's material

6.34.3.4 enable_variable_specific_heat()

void IRockyParticleScalarsModel::enable_variable_specific_heat ( )

Enables a known-scalar defining specific heat value to each particle in a simulation.

When this scalar is enabled, the instantaneous specific heat is defined as a variable
property, with possibly a different value and used everywhere in the simulation,
instead of the constant value of particle's material

6.34.3.5 enable_variable_thermal_conductivity()

void IRockyParticleScalarsModel::enable_variable_thermal_conductivity ( )

Enables a known-scalar that defines the thermal conductivity as a variable property

between particles. When this scalar is enabled, a different value of thermal

© 2022, esss - all rights reserved

ROCKY api : solver manual 196

conductivity can be specified for each particle in a simulation, and this value
will be used everywhere in the Rocky solver instead of the constant value specified
for the particle's material in the Rocky UI.

6.34.3.6 enable_volume_increment()

void IRockyParticleScalarsModel::enable_volume_increment ( )

Enables a known-scalar that associates a volume increment value to each particle in

a simulation. When this scalar is enabled, the instantaneous volume of a particle is
equal to the original volume defined at the beginning of a simulation plus the value
of that volume increment.

6.34.3.7 find()

int IRockyParticleScalarsModel::find ( const char ∗ name )

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:
name The name given to the scalar at the moment of its creation.

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

6.34.3.8 reset()

void IRockyParticleScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:
scalar_index The index attributed to the scalar variable at the moment of its creation.

6.34.3.9 set_dimension()

void IRockyParticleScalarsModel::set_dimension ( int scalar_index, double dimension_factor

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 197

scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

6.35 IRockyParticleTransferScalars struct reference

#include <rocky_particle_scalars.hpp>

6.35.1 Public member functions

 ROCKY_FUNCTIONS double get_heat_transfer () const
 ROCKY_FUNCTIONS void set_heat_transfer (const double value)
 ROCKY_FUNCTIONS void add_heat_transfer (const double value)
 ROCKY_FUNCTIONS void add_heat_source (const double value)
 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const
 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.35.2 Detailed description

When running a simulation, an IRockyParticleTransferScalars gives access to all

particle transfer scalars defined in the project. Particle transfer scalars are special
particle scalars whose values are reset automatically to zero at the beginning of a
new time iteration.

6.35.3 Member function documentation

6.35.3.1 add_heat_source()

ROCKY_FUNCTIONS void IRockyParticleTransferScalars::add_heat_source ( const double value )

This method adds a value to the source term to the thermal energy balance equation
of a particle. The added value can be positive (heat is generated) or negative (heat
is removed).

Parameters:

value The value of the thermal energy per unit time generated in or removed from the particle.

© 2022, esss - all rights reserved

ROCKY api : solver manual 198

6.35.3.2 add_heat_transfer()

ROCKY_FUNCTIONS void IRockyParticleTransferScalars::add_heat_transfer ( const double value

This method sums a value to the current heat transfer rate to the particle.

Parameters:
value The value summed to the heat transfer rate.

6.35.3.3 add_scalar()

ROCKY_FUNCTIONS void IRockyParticleTransferScalars::add_scalar ( int scalar_index, double

value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.35.3.4 get_heat_transfer()

ROCKY_FUNCTIONS double IRockyParticleTransferScalars::get_heat_transfer ( ) const

Returns:
The value of the total heat transfer rate to the particle at a given time. This is a built-in particle
scalar defined inside the solver, enabled whenever a thermal model is active in the project.

6.35.3.5 get_scalar()

ROCKY_FUNCTIONS double IRockyParticleTransferScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

6.35.3.6 max_scalar()

ROCKY_FUNCTIONS void IRockyParticleTransferScalars::max_scalar ( int scalar_index, double

value ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 199

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common
use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.35.3.7 set_heat_transfer()

ROCKY_FUNCTIONS void IRockyParticleTransferScalars::set_heat_transfer ( const double value

This method sets the value of the heat transfer rate to the particle. This value will
be used in the thermal energy balance equation of the particle in order to update its
temperature at the following timestep.

Parameters:
value The value of the heat transfer rate.

6.35.3.8 set_scalar()

ROCKY_FUNCTIONS void IRockyParticleTransferScalars::set_scalar ( int scalar_index, double

value ) const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.36 IRockyParticleTransferScalarsModel struct refer-

ence
#include <rocky_particle_scalars.hpp>

6.36.1 Public member functions

 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)

© 2022, esss - all rights reserved

ROCKY api : solver manual 200

6.36.2 Detailed description

An IRockyParticleTransferScalarsModel allows users to add new particle transfer

scalars, find particle transfer scalars created in other modules or activate particle
transfer scalars known to Rocky, during the setup stage of a module. Particle
transfer scalars are special particle scalars whose values are reset automatically to
zero at the beginning of a new time iteration.

6.36.3 Member function documentation

6.36.3.1 add()

int IRockyParticleTransferScalarsModel::add ( const char ∗ name, const char ∗ unit, bool

output = true )

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:

name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.36.3.2 find()

int IRockyParticleTransferScalarsModel::find ( const char ∗ name )

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:

name The name given to the scalar at the moment of its creation.

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

© 2022, esss - all rights reserved

ROCKY api : solver manual 201

6.36.3.3 reset()

void IRockyParticleTransferScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:

scalar_index The index attributed to the scalar variable at the moment of its creation.

6.36.3.4 set_dimension()

void IRockyParticleTransferScalarsModel::set_dimension ( int scalar_index, double dimension←-

_factor )

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:
scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

6.37 IRockyTriangleScalars struct reference

#include <rocky_triangle_scalars.hpp>

6.37.1 Public member functions

 ROCKY_FUNCTIONS double get_thermal_conductivity () const
 ROCKY_FUNCTIONS void set_thermal_conductivity (const double value)
 ROCKY_FUNCTIONS double get_poisson_ratio () const
 ROCKY_FUNCTIONS void set_poisson_ratio (const double value)
 ROCKY_FUNCTIONS double get_scalar (int scalar_index) const
 ROCKY_FUNCTIONS void set_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void add_scalar (int scalar_index, double value) const
 ROCKY_FUNCTIONS void max_scalar (int scalar_index, double value) const

6.37.2 Detailed description

Triangle scalars are special variables within the Rocky solver that associate a value
to each one of the geometry triangles that make up the geometries in the project.

© 2022, esss - all rights reserved

ROCKY api : solver manual 202

When running a simulation, an IRockyTriangleScalars object gives access to all

triangle scalars defined in the project. These triangle scalars can be built-in scalars
defined in the solver, or custom triangle scalars defined by the current module or
other active modules.

6.37.3 Member function documentation

6.37.3.1 add_scalar()

ROCKY_FUNCTIONS void IRockyTriangleScalars::add_scalar ( int scalar_index, double value )

const

If a custom scalar variable was defined during the setup of the module, this method
can be used to sum a value to the current one stored in it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be summed to the current stored value.

6.37.3.2 get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyTriangleScalars::get_poisson_ratio ( ) const

Returns:
The value of the Poisson's ratio assigned to the geometry triangle. The Rocky solver has a built-in
triangle scalar that once enabled allow triangles to have associated a variable thermal conductivity,
which overrides the constant value specified for the geometry's material.

6.37.3.3 get_scalar()

ROCKY_FUNCTIONS double IRockyTriangleScalars::get_scalar ( int scalar_index ) const

If a custom scalar variable was defined during the setup of the module, the value
currently stored can be accessed with this method.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.

Returns:
The value currently stored in the scalar variable.

6.37.3.4 get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyTriangleScalars::get_thermal_conductivity ( ) const

© 2022, esss - all rights reserved

ROCKY api : solver manual 203

Returns:
The value of the thermal conductivity of the geometry triangle. The Rocky solver has a built-in
triangle scalar that once enabled allow triangles to have associated a variable thermal conductivity,
which overrides the constant value specified for the geometry's material.

6.37.3.5 max_scalar()

ROCKY_FUNCTIONS void IRockyTriangleScalars::max_scalar ( int scalar_index, double value )

const

If a custom scalar variable was defined during the setup of the module, this method
can be used to make the scalar store the maximum of a set of values. A common
use of this method is, for instance, to find the maximum among a set of values
associated to the contacts of a particle.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value A value that must be checked if it is greater than the current stored value.

6.37.3.6 set_poisson_ratio()

ROCKY_FUNCTIONS void IRockyTriangleScalars::set_poisson_ratio ( const double value )

This method sets the value of the Poisson's ratio for the associated geometry triangle,
if the corresponding built-in triangle scalar was enabled. Otherwise, a segmentation
fault will occur.

Parameters:
value The value of the Poisson's ratio for the geometry triangle.

6.37.3.7 set_scalar()

ROCKY_FUNCTIONS void IRockyTriangleScalars::set_scalar ( int scalar_index, double value )

const

If a custom scalar variable was defined during the setup of the module, this method
can be used to store a value on it.

Parameters:
scalar_index The integer index that was associated to the scalar variable during the setup of
the module.
value The value that must be stored.

6.37.3.8 set_thermal_conductivity()

ROCKY_FUNCTIONS void IRockyTriangleScalars::set_thermal_conductivity ( const double value )

© 2022, esss - all rights reserved

ROCKY api : solver manual 204

This method sets the value of the thermal conductivity for the associated geometry
triangle, if the corresponding built-in triangle scalar was enabled. Otherwise, a
segmentation fault will occur.

Parameters:

value The value of the triangle's thermal conductivity.

6.38 IRockyTriangleScalarsModel struct reference

#include <rocky_triangle_scalars.hpp>

6.38.1 Public member functions

 int find (const char ∗name)
 int add (const char ∗name, const char ∗unit, bool output=true)
 void reset (int scalar_index)
 void set_dimension (int scalar_index, double dimension_factor)

6.38.2 Detailed description

IRockyTriangleScalarsModel allows users to add new triangle scalars, find triangle

scalars created in other modules or activate triangle scalars known to Rocky, during
the setup phase of a module. Triangle scalars are special variables attached to
boundary triangles, which are able to store values per triangle that are preserved
between time iterations during a simulation.

6.38.3 Member function documentation

6.38.3.1 add()

int IRockyTriangleScalarsModel::add ( const char ∗ name, const char ∗ unit, bool output =
true )

This method creates a new scalar variable in order to store values during a
simulation, preserving them between time iterations.

Parameters:

© 2022, esss - all rights reserved

ROCKY api : solver manual 205

name The name given to the scalar variable. The purpose of this name is twofold. First, it
enables to find this scalar variable from other module, in order to share their values.
Second, if the scalar variable can be displayed in a 3D window as a property, this name
will identify it in the Rocky UI.

unit A string specifying the unit in S.I. associated to the scalar variable.

output Enables/disables the storage in disk at output times, for the visualization and post-
processing of the scalar values.

Returns:
The index that will uniquely identify the scalar variable during the execution of the simulation.

6.38.3.2 find()

int IRockyTriangleScalarsModel::find ( const char ∗ name )

This method searches for a scalar variable already created by other modules, in
order to allow access to its values, or store new values on it, during the execution of
the simulation.

Parameters:
name The name given to the scalar at the moment of its creation.

Returns:
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

6.38.3.3 reset()

void IRockyTriangleScalarsModel::reset ( int scalar_index )

This method resets to zero all values stored in a scalar variable.

Parameters:
scalar_index The index attributed to the scalar variable at the moment of its creation.

6.38.3.4 set_dimension()

void IRockyTriangleScalarsModel::set_dimension ( int scalar_index, double dimension_factor

The purpose of this method is to associate a dimensional factor to a scalar variable.

This factor will be used to nondimensionalize their values. For instance, if the
scalar represents a force, a force dimensional factor must be associated through
this method. Dimensional factors for the fundamental magnitudes are provided by
functions of a IRockyModel object.

Parameters:
scalar_index The index attributed to the scalar variable at the moment of its creation.
dimension_factor The appropriate dimensional factor for the scalar variable.

© 2022, esss - all rights reserved