Setting up a Project and Debugging with Visual Studio

Transcription

1 Setting up a Project and Debugging with Visual Studio Contents Setup Visual Studio to compile a DLL Step 1: Install Visual Studio Express 2013 for Windows Desktop Step 2: Create a New Project Step 3: Add source files to project Step 4: Compile the model Step 5: Debug vs Release Debugging using Visual Studio Express 2013 for Windows Desktop Step 1: Configure Visual C++ Expression edition for debugging Step 2: Use Breakpoint and Watch Value Step 4: Use conditional breakpoint Setup Visual Studio to compile a DLL Setting up a project in Visual Studio allows you to compile your contact models, particle body force models and custom factories to a DLL without the need to use the command line. It also has advantages for debugging such as attaching to the EDEM process and interrogating values passed to your model on the fly. Step 1: Install Visual Studio Express 2013 for Windows Desktop If you haven t already, you can download Visual Studio Express from this location: To download it you will need to use a Microsoft Account, if you don t have one you can create it providing your name, valid address and introducing a password.

2 Step 2: Create a New Project 1. After opening Visual Studio Express 2013, go to File > New Project... Select Win32 Project in the Visual C++ templates list 2. Enter a project name and location and press OK (In this demonstration the project is called HM_Contact_Model and is located at C:\API\Hertz- Mindlin\ 3. On the next page go to Application Settings Compiling Guide DEM Solutions Page 2 of 13

3 4. Select DLL 5. Select Empty Project 6. Uncheck Security Development Lifecycle (SDL). This option turns some warnings into errors. For example the use of the function strcpy which is considered unsafe will trigger an error instead of a warning. Since many shared API models available on DEM Solutions forum use strcpy, we recommend not checking this option. 7. Press Finish Step 3: Add source files to project There are many example source files available through the EDEM User Forum, for this demonstration we are going to use the Hertz-Mindlin Contact Model which is available here: The packaged zip file already contains the whole visual studio project. For the purpose of this presentation we will only need some of the source files. 1. Copy the following source files from the src folder: a. CHertzHindlin.cpp b. CHertzMindlin.h c. HertzMindlin.cpp 2. Paste those source files to your newly created project folder; Visual Studio will have already created other files in the folder. (In this demonstration, the project folder is C:\API\Hertz-Mindlin\HM_Contact_Model) Compiling Guide DEM Solutions Page 3 of 13

4 3. Add the *.cpp files to the Visual Studio project. In Visual Studio > Solution Explorer > Source Files (right click) > Add > Existing Item... (You can also drag and drop) Select both *.cpp files and press OK Compiling Guide DEM Solutions Page 4 of 13

5 4. Add the header files (*.h) to the Visual Studio project. In Visual Studio > Solution Explorer > Header Files (right click) > Add > Existing Item... Select both *.h files and press OK Compiling Guide DEM Solutions Page 5 of 13

6 5. The example source code files have now been added but other EDEM header files are needed before the contact model will compile to a DLL. The additional header files required are installed on your system by the EDEM installer and will be at the following location: C:\Program Files\DEM Solutions\EDEM 2.X\src\Api (where X is the version of EDEM you are currently using From the Core folder copy the following files to your project directory: ApiIds.h ApiTypes.h IApi.h IApiManager_1_0.h ICustomPropertyDataApi_1_0 ICustomPropertyManagerApi_1_0 PluginConstants.h From the ContactModels folder copy the following files to your project directory: IPluginContactModel.h IPluginContactModelV2_3_0.h PluginContactModelCore.h From the C:\Program Files\DEM Solutions\EDEM 2.X\src\Misc, copy the Helpers.h file. It contains some mathematical operators such as vector and matrix and their associated operations (cross product, matrix inversion ) that can be used easily in your API model. Note: there are additional header files in each folder but they aren t required for this project. If you aren t sure which header files you need then add all of them to your project, the compiler will simply ignore any files it doesn t need. Besides when creating a custom body force or a custom factory, you will need to copy the header files respectively from the ParticleBodyForce or Factories folders. 6. Add these additional header files to your project as before. The solution explorer should look like this: Compiling Guide DEM Solutions Page 6 of 13

7 Step 4: Compile the model 1. The first step consists in setting up the compiler to compile in 64 bits. To do that open the configuration: 2. Create a new solution platform: Compiling Guide DEM Solutions Page 7 of 13

8 3. Select x64 and press OK. 4. You can compile your dll by clicking ion Build > Build Solution Compiling Guide DEM Solutions Page 8 of 13

9 If successful, the Output window at the bottom of Visual Studio will confirm Build: 1 succeeded and it will also give you the location of the newly created *.DLL. (Note: If the build fails you will also be given useful information in this window as to why it has failed. Always start with the first error message in the list as this is also likely to be the cause of many of the following errors). In case you made modification to the model and you want to create a new DLL, select Build > Rebuild Solution to recreate a new DLL. Step 5: Debug vs Release In the previous step we compiled the library in Debug mode. This mode includes additional code in the library which allows Visual Studio to interrogate the library while running and can be very useful while modifying the code. Once the library is complete and the library is being used to run simulations this code is no longer required and will slow down the performance of EDEM. To remove this additional code and to allow the compiler to optimise the library for performance, change Visual Studio to Release mode. You need to re-compile after changing the mode ( Debug > Build Solution ). (Note: The release build of your library will be created in a different location to the debug version so make sure to check the output window for details.) Compiling Guide DEM Solutions Page 9 of 13

10 Debugging using Visual Studio Express 2013 for Windows Desktop Step 1: Configure Visual C++ Expression edition for debugging 1. Make sure EDEM is running and click on Debug > Attach to Process 2. Select edem.exe in the list and click on Attach. If the process has been done correctly at bottom of Visual Studio Express 2013 will be similar to: 3. Load the library into EDEM a. Select Tools > Options > File Locations in EDEM and be sure the location point to the folder containing the debug version of your dll. In our case C:/API/Hertz-Mindlin/HM_Contact_Model/x64/Debug/ b. Load a simulation that is using the Hertz-Mindlin built-in contact model or setup a new one. Compiling Guide DEM Solutions Page 10 of 13

11 c. In both Particle to Particle and Particle to Geometry Interaction in the Physics section of the Creator, remove the Hertz-Mindlin (no slip) contact model and click on the + button our API model, HM_Contact_Model, appears at the bottom of the list. Add it in both case. d. Similarly custom body forces are added in the Particle Body Force interaction while custom factories are added in the Factories tab of the creator by clicking on the Transfer button. Make you have also selected the appropriate folder File Locations. Step 2: Use Breakpoint and Watch Value 1. In Visual Studio, you can add a break point by clicking on left hand side of the source code window. The simulation will stop once the break point is encountered 2. Make sure your run it using 1 core before running the simulation in EDEM. This prevents the break points to be hit by different thread which can be confusing when debugging. 3. Once the simulation has stopped, you can execute one instruction at a time by pressing the F10 key or the button. The red point indicates the breakpoint while the yellow arrow indicates the next line to be executed when F10 is pushed. Tip: In case that your break point are a symbol instead of, it means that the DLL load in the EDEM is not the same as the code in the project, so the code won t stop in this points when you run the simulation. Make sure that you are loading the correct DLL (section Step 1-3.a) into Compiling Guide DEM Solutions Page 11 of 13

12 EDEM and also that you have attached to the correct EDEM deck in case you have multiple EDEM decks open in the GUI. e.g Load Release DLL instead of Debug 4. It is possible to see the value contained by a variable. To do that, hovering it with your mouse or right click on it and click on Add to watch to add it to your watch variable: Here we watch the double variable time and the CSimple3DVector relvel. A CSimple3DVector is a vector object defined in the Helper.h file mentioned previously. By expanding it, we can see the three components X, Y and Z of the vector. A variable is in red when its the value has changed since the last time the simulation has paused. In the present case relvel was added to the watch variables before pressing the F10 key. Since the last instruction that has been executed has modified revel, it shows in red. However the variable time has not changed and it is in black. 5. If you Press F5, the simulation will run until the breakpoint is hit again, in other word when another computation of the contact force is required. Step 4: Use conditional breakpoint 1. The use of conditional break point allows you to stop the stimulation at a break point under a certain condition. For instance in the following screenshot, the condition is that the value of the variable time is more than 1 (second). To enable breakpoint condition, right click on a breakpoint and click Condition. Compiling Guide DEM Solutions Page 12 of 13

13 2. Press F5 The simulation has stopped at the first time step after 1s where a contact is detected. Both time and relvel are in red since their values have changed compared so the previous time the simulation had paused (in the current example, relvel will only be initialized once the next instruction is executed hence the odd numerical values for the X, Y and Z components). 3. You can click on the square button to stop the debugging. The simulation will continue normally. Compiling Guide DEM Solutions Page 13 of 13