When developing your Ansys Rocky™ Custom Modules using the Rocky Solver SDK, running into errors or unexpected behaviors is part of the process.
Whether you are extending particle behavior, creating custom post-processing tools, or integrating with external solvers, efficient debugging is essential to ensure your module works as intended.
In this article, we will walk through a step-by-step approach to debugging your own custom modules -- from setting up your development environment to interpreting log messages and using external tools like Visual Studio for deeper inspection.
1. Use Rocky Simulation Log file for information
Rocky software provides a simulation log file which contains simple information, such as hardware details, to more complex data about the simulation, such as particles, triangles, and contacts information; memory consumption and free memory; and other solver process information.
These outputs can help you trace what your module is doing, which can be useful for debugging purposes.
Example simulation log file location
Visit the Rocky User Manual for more details about the Simulation log file.
You can also find some information in a more simplified form in the Simulation log panel within Rocky, which displays any solver-related warnings, errors, or other information that happen during processing, no matter whether you are running your simulations using CPU or GPU resources.
Simulation Log panel showing some warnings and information that was logged during processing
Visit the Rocky User Manual for more details about the Simulation log panel.
2. Use Print Statements or Logging in your code
Sometimes, the simplest way to check if your code is running as expected is to insert print/log lines in strategic parts.
Examples of code lines to print:
ROCKY_MESSAGE_LOG("SPHModelAPIAddin: configure");
ROCKY_INFO_LOG("SPHModelAPIAddin: initialize_cuda");
ROCKY_WARNING_LOG("Text");
In this way you can print values in the log and use the Rocky application to debug.
3. Use Auxiliary Scalars to identify calculations errors
You can also create auxiliary scalars with intermediate values to help you identify possible calculation errors and later visualize them during the simulation in the 3D view.
4. Check for compilation and Linking Errors
To prepare your system for building custom modules for Rocky software using the Solver SDK, you need to install and set up a few components, including environment variables.
-
Ensure that all components were added correctly using the Installation Guide Modules and Scripts within SDK and Modules (Full Package) in Ansys Customer Portal.
-
Always clean and rebuild if you are unsure.
Important: Check the version of Solver SDK you are using and make sure it is the same as the Rocky software. Mixing packages from different versions may generate an error.
5. Use the VS Code to debug Ansys Rocky Custom Modules
Below is a workflow you can follow for building and debugging your code:
-
Download and install VS Code.
Note: In this step-by-step, the version used was 1.67.2.
-
Launch VS Code and install the following extensions:
- C/C ++ Extension Pack (Microsoft)
- CMake (twxs)
- CMake Tools (Microsoft)
-
Close and Launch VS Code again.
-
Go to File, then Open folder, and open the Module Folder you are currently working on.
-
Configure the compiling options as shown below:
-
Click on Build:
This should compile the module with Debug info and also install the .dlls and python file in the module's folder. If everything went right during compilation, your module can now be debugged.
In order to do that, we need to launch Rocky and attach the debugger in the Solver.
-
Create a folder inside the module folder and name it .vscode (with a dot in the name).
-
Go to the Run and Debug in the left panel and click on create a launch.json file.
-
Select the first option you see, for example, Edge: Launch.
-
Delete the content of the configurations list and click on Add Configuration.
-
Choose the option C/C++: (Windows) Start/Launch. It should look like this:
{ "version": "0.2.0", "configurations": [ { "name": "(Windows) Attach", "type": "cppvsdbg", "request": "attach" }, { "name": "(Windows) Launch", "type": "cppvsdbg", "request": "launch", "program": "Indlude the path to the Rocky executable", "args": [], "stopAtEntry": false, "cwd": "${fileDirname}", "environment": [], "console": "externalTerminal" } ] } -
Now we just need to supply the path for the Rocky Solver and the solver arguments.
To make it easier to understand, you can open the simulation log file of any Rocky project, found under the simulation folder and named as rocky_simulation.rocky20.log. Right after the file header, you will see the command line that was used to launch the Rocky Solver:
</message> <message date="2022-05-13 14:15:20" up_time="0:0:0.0"> Command line: C:\Program Files\ESSS\Rocky 2022 R1\bin\RockySolver.exe --rcy-file=C:\Users\vdaroz\Documents\Delete\freeze_roi.rocky.files\simulation/rocky_simulation.rocky20 --license=C:\Users\vdaroz\AppData\Roaming\Rocky\license.lic --ncpus=4 </message> -
We just need to copy that information to the launch.json file. It should look like:
Have in mind that we have changed the argument --ncpus to 1 instead of 4.
We recommend debugging using only 1 CPU. Debugging in parallel is much more complicated.
-
As soon as you have the launch.json file set up, you just need to create the breakpoints wherever you need, go to Run and Debug in the left panel in VS Code, and click the launch button.
If it works, you will see everything working properly.
With practice, debugging becomes not just a troubleshooting step, but a key part of writing robust Rocky Custom Modules, enabling detailed logging and using tools like Visual Studio, you can identify and resolve issues more efficiently.
Keep iterating, stay curious, and do not hesitate to dive deeper into Solver SDK examples in the Rocky Solver SDK Manual.