DEME 2.0.3__tar.gz → 2.0.5__tar.gz

{deme-2.0.3/deme.egg-info → deme-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: deme
-Version: 2.0.3
+Version: 2.0.5
 Summary: PyBind Wrapper Library for DEM-Engine
 Home-page: UNKNOWN
 Author: Ruochun Zhang

{deme-2.0.3 → deme-2.0.5}/README.md

@@ -85,6 +85,8 @@ pip3 install DEME
 
 Then [Python scripts](https://github.com/projectchrono/DEM-Engine/tree/pyDEME_demo/src/demo) can be executed in this environment. To understand the content of each Python demo, refer to the explanations of the C++ demos with the same names in <a href="#examples">Numerical examples</a> section.
 
+If you use _pyDEME_ in conjunction with PyChrono, you should `import pyDEME` first, then PyChrono.
+
 <h2 id="compilation">Compilation</h2>
 
 You can also build C++ _DEME_ from source. It allows for potentially more performance and more tailoring.

{deme-2.0.3 → deme-2.0.5/deme.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: deme
-Version: 2.0.3
+Version: 2.0.5
 Summary: PyBind Wrapper Library for DEM-Engine
 Home-page: UNKNOWN
 Author: Ruochun Zhang

{deme-2.0.3 → deme-2.0.5}/setup.py

@@ -152,7 +152,7 @@ class CMakeBuild(build_ext):
 # logic and declaration, and simpler if you include description/version in a file.
 setup(
     name="deme",
-    version="2.0.3",
+    version="2.0.5",
     author="Ruochun Zhang",
     author_email="ruochunz@gmail.com",
     description="PyBind Wrapper Library for DEM-Engine",

{deme-2.0.3 → deme-2.0.5}/src/DEM/API.h

@@ -88,8 +88,11 @@ class DEMSolver {
     /// Set the initial time step size. If using constant step size, then this will be used throughout; otherwise, the
     /// actual step size depends on the variable step strategy.
     void SetInitTimeStep(double ts_size) { m_ts_size = ts_size; }
-    /// Return the number of clumps that are currently in the simulation.
+    /// Return the number of clumps that are currently in the simulation. Must be used after initialization.
     size_t GetNumClumps() const { return nOwnerClumps; }
+    /// Return the total number of owners (clumps + meshes + analytical objects) that are currently in the simulation.
+    /// Must be used after initialization.
+    size_t GetNumOwners() const { return nOwnerBodies; }
     /// @brief Get the number of kT-reported potential contact pairs.
     /// @return Number of potential contact pairs.
     size_t GetNumContacts() const { return dT->getNumContacts(); }
@@ -125,6 +128,10 @@ class DEMSolver {
     /// Get the jitification string substitution laundary list. It is needed by some of this simulation system's friend
     /// classes.
     std::unordered_map<std::string, std::string> GetJitStringSubs() const { return m_subs; }
+    /// Get current jitification options. It is needed by some of this simulation system's friend classes.
+    std::vector<std::string> GetJitifyOptions() const { return m_jitify_options; }
+    /// Set the jitification options. It is only needed by advanced users.
+    void SetJitifyOptions(const std::vector<std::string>& options) { m_jitify_options = options; }
 
     /// Explicitly instruct the bin size (for contact detection) that the solver should use.
     void SetInitBinSize(double bin_size) {
@@ -413,7 +420,7 @@ class DEMSolver {
 
     /// @brief Get the clumps that are in contact with this owner as a vector.
     /// @details No multi-owner bulk version. This is due to efficiency concerns. If getting multiple owners' contacting
-    /// clumps is needed, use family-based GetClumpContacts method, then the owner ID list-based c method if you further
+    /// clumps is needed, use family-based GetContacts method, then the owner ID list-based c method if you further
     /// need the contact forces information.
     /// @param ownerID The ID of the owner that is being queried.
     /// @return Clump owner IDs in contact with this owner.
@@ -487,18 +494,25 @@ class DEMSolver {
     /// @return A vector of float3 representing the global coordinates of the mesh nodes.
     std::vector<float3> GetMeshNodesGlobal(bodyID_t ownerID);
 
-    /// @brief Get all clump--clump contacts in the simulation system.
+    /// @brief Get all clump--clump contact ID pairs in the simulation system. Note all GetContact-like methods reports
+    /// potential contacts (not necessarily confirmed contacts), meaning they are similar to what
+    /// WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
     /// @return A sorted (based on contact body A's owner ID) vector of contact pairs. First is the owner ID of contact
     /// body A, and Second is that of contact body B.
     std::vector<std::pair<bodyID_t, bodyID_t>> GetClumpContacts() const;
-
-    /// @brief Get all clump--clump contacts in the simulation system.
+    /// @brief Get all clump--clump contact ID pairs in the simulation system. Note all GetContact-like methods reports
+    /// potential contacts (not necessarily confirmed contacts), meaning they are similar to what
+    /// WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
     /// @param family_to_include Contacts that involve a body in a family not listed in this argument are ignored.
     /// @return A sorted (based on contact body A's owner ID) vector of contact pairs. First is the owner ID of contact
     /// body A, and Second is that of contact body B.
     std::vector<std::pair<bodyID_t, bodyID_t>> GetClumpContacts(const std::set<family_t>& family_to_include) const;
-
-    /// @brief Get all clump--clump contacts in the simulation system.
+    /// @brief Get all clump--clump contact ID pairs in the simulation system. Note all GetContact-like methods reports
+    /// potential contacts (not necessarily confirmed contacts), meaning they are similar to what
+    /// WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
     /// @param family_pair Functions returns a vector of contact body family number pairs. First is the family number of
     /// contact body A, and Second is that of contact body B.
     /// @return A sorted (based on contact body A's owner ID) vector of contact pairs. First is the owner ID of contact
@@ -506,6 +520,51 @@ class DEMSolver {
     std::vector<std::pair<bodyID_t, bodyID_t>> GetClumpContacts(
         std::vector<std::pair<family_t, family_t>>& family_pair) const;
 
+    /// @brief Get all contact ID pairs in the simulation system. Note all GetContact-like methods reports potential
+    /// contacts (not necessarily confirmed contacts), meaning they are similar to what
+    /// WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
+    /// @return A sorted (based on contact body A's owner ID) vector of contact pairs. First is the owner ID of contact
+    /// body A, and Second is that of contact body B.
+    std::vector<std::pair<bodyID_t, bodyID_t>> GetContacts() const;
+    /// @brief Get all contact ID pairs in the simulation system. Note all GetContact-like methods reports potential
+    /// contacts (not necessarily confirmed contacts), meaning they are similar to what
+    /// WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
+    /// @param family_to_include Contacts that involve a body in a family not listed in this argument are ignored.
+    /// @return A sorted (based on contact body A's owner ID) vector of contact pairs. First is the owner ID of contact
+    /// body A, and Second is that of contact body B.
+    std::vector<std::pair<bodyID_t, bodyID_t>> GetContacts(const std::set<family_t>& family_to_include) const;
+    /// @brief Get all contact ID pairs in the simulation system. Note all GetContact-like methods reports potential
+    /// contacts (not necessarily confirmed contacts), meaning they are similar to what
+    /// WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
+    /// @param family_pair Functions returns a vector of contact body family number pairs. First is the family number of
+    /// contact body A, and Second is that of contact body B.
+    /// @return A sorted (based on contact body A's owner ID) vector of contact pairs. First is the owner ID of contact
+    /// body A, and Second is that of contact body B.
+    std::vector<std::pair<bodyID_t, bodyID_t>> GetContacts(
+        std::vector<std::pair<family_t, family_t>>& family_pair) const;
+
+    /// @brief Get all contact pairs' detailed information (actual content based on the setting with
+    /// SetContactOutputContent; default are owner IDs, contact point location, contact force, and associated wildcard
+    /// values) in the simulation system. Note all GetContact-like methods reports potential contacts (not necessarily
+    /// confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what
+    /// WriteContactFile does.
+    /// @details Do not call this method with high frequency, as it is not efficient.
+    /// @param force_thres Only contacts with force larger than this value are returned. Setting it to a small positive
+    /// number to, instead of getting all potential contacts, only get the ones that are currently confirmed to generate
+    /// force.
+    /// @return A map that may have the following keys: "ContactType", "Point", "AOwner", "BOwner", "AOwnerFamily",
+    /// "BOwnerFamily", "Force", "Torque", "Normal" and wildcard names, each corresponding to a vector of values. The
+    /// "ContactType" is a vector of strings, each indicating the type of contact (e.g., "sphere-sphere",
+    /// "sphere-triangle", etc.). The "Point" is a vector of float3s, each indicating the contact point location in
+    /// global coordinates. The "AOwner" and "BOwner" are vectors of body IDs for the two bodies in contact. The "Force"
+    /// is a vector of float3s, each indicating the contact force at the contact point. The "Torque" is a vector of
+    /// float3s, each indicating the torque at the contact point. The "Normal" is a vector of float3s, each indicating
+    /// the normal direction at the contact point.
+    std::shared_ptr<ContactInfoContainer> GetContactDetailedInfo(float force_thres = -1.0) const;
+
     /// @brief Get the host memory usage (in bytes) on dT.
     /// @return Number of bytes.
     size_t GetHostMemUsageDynamic() const { return dT->estimateHostMemUsage(); }
@@ -1046,7 +1105,17 @@ class DEMSolver {
     /// @param force_thres Forces with magnitude smaller than this amount will not be outputted.
     void WriteContactFile(const std::string& outfilename, float force_thres = DEME_TINY_FLOAT) const;
     void WriteContactFile(const std::filesystem::path& outfilename) const { WriteContactFile(outfilename.string()); }
-    /// Write the current status of all meshes to a file
+    /// @brief Write all contact pairs kT-supplied to a file, thus including the potential ones (those are not yet in
+    /// contact, or recently used to be in contact).
+    /// @details The outputted torque using this method is in global, rather than each object's local coordinate system.
+    /// @param outfilename Output filename.
+    void WriteContactFileIncludingPotentialPairs(const std::string& outfilename) const {
+        WriteContactFile(outfilename, -1.0);
+    }
+    void WriteContactFileIncludingPotentialPairs(const std::filesystem::path& outfilename) const {
+        WriteContactFileIncludingPotentialPairs(outfilename.string());
+    }
+    /// Write the current status of all meshes to a file.
     void WriteMeshFile(const std::string& outfilename) const;
     void WriteMeshFile(const std::filesystem::path& outfilename) const { WriteMeshFile(outfilename.string()); }
 
@@ -1345,8 +1414,8 @@ class DEMSolver {
     // The output file format for contact pairs
     OUTPUT_FORMAT m_cnt_out_format = OUTPUT_FORMAT::CSV;
     // The output file content for contact pairs
-    unsigned int m_cnt_out_content = CNT_OUTPUT_CONTENT::GEO_ID | CNT_OUTPUT_CONTENT::FORCE |
-                                     CNT_OUTPUT_CONTENT::DEME_POINT | CNT_OUTPUT_CONTENT::CNT_WILDCARD;
+    unsigned int m_cnt_out_content = CNT_OUTPUT_CONTENT::OWNER | CNT_OUTPUT_CONTENT::FORCE |
+                                     CNT_OUTPUT_CONTENT::CNT_POINT | CNT_OUTPUT_CONTENT::CNT_WILDCARD;
     // The output file format for meshes
     MESH_FORMAT m_mesh_out_format = MESH_FORMAT::VTK;
     // If the solver should output wildcards to file
@@ -1577,6 +1646,8 @@ class DEMSolver {
 
     // A big fat tab for all string replacement that the JIT compiler needs to consider
     std::unordered_map<std::string, std::string> m_subs;
+    // jitify's compilation options
+    std::vector<std::string> m_jitify_options = DEME_JITIFY_DEFAULT_OPTIONS;
 
     // A map that records the numbering for user-defined owner wildcards
     std::unordered_map<std::string, unsigned int> m_owner_wc_num;

{deme-2.0.3 → deme-2.0.5}/src/DEM/APIPrivate.cpp

@@ -306,12 +306,12 @@ void DEMSolver::jitifyKernels() {
     // Jitify may require a defined device to derive the arch
     std::thread kT_build([&]() {
         DEME_GPU_CALL(cudaSetDevice(kT->streamInfo.device));
-        kT->jitifyKernels(m_subs);
+        kT->jitifyKernels(m_subs, m_jitify_options);
     });
 
     std::thread dT_build([&]() {
         DEME_GPU_CALL(cudaSetDevice(dT->streamInfo.device));
-        dT->jitifyKernels(m_subs);
+        dT->jitifyKernels(m_subs, m_jitify_options);
 
         // Now, inspectors need to be jitified too... but the current design jitify inspector kernels at the first time
         // they are used. for (auto& insp : m_inspectors) {
@@ -321,7 +321,7 @@ void DEMSolver::jitifyKernels() {
         // Solver system's own max vel inspector should be init-ed. Don't bother init-ing it while using, because it is
         // called at high frequency, let's save an if check. Forced initialization (since doing it before system
         // completes init).
-        m_approx_max_vel_func->Initialize(m_subs, true);
+        m_approx_max_vel_func->Initialize(m_subs, m_jitify_options, true);
         dT->approxMaxVelFunc = m_approx_max_vel_func;
     });
     kT_build.join();
@@ -1379,6 +1379,7 @@ inline void DEMSolver::equipForceModel(std::unordered_map<std::string, std::stri
     std::set<std::string> added_owner_wildcards, added_geo_wildcards;
     // Analyze this model... what does it require?
     std::string model = m_force_model[DEFAULT_FORCE_MODEL_NAME]->m_force_model;
+    std::string model_prerequisites = m_force_model[DEFAULT_FORCE_MODEL_NAME]->m_model_prerequisites;
     const std::set<std::string> contact_wildcard_names = m_force_model[DEFAULT_FORCE_MODEL_NAME]->m_contact_wildcards;
     const std::set<std::string> owner_wildcard_names = m_force_model[DEFAULT_FORCE_MODEL_NAME]->m_owner_wildcards;
     const std::set<std::string> geo_wildcard_names = m_force_model[DEFAULT_FORCE_MODEL_NAME]->m_geo_wildcards;
@@ -1539,6 +1540,7 @@ inline void DEMSolver::equipForceModel(std::unordered_map<std::string, std::stri
         contact_info_write_strat = compact_code(contact_info_write_strat);
     }
     strMap["_DEMForceModel_"] = model;
+    strMap["_forceModelPrerequisites_;"] = model_prerequisites;
     strMap["_forceModelIngredientDefinition_"] = ingredient_definition;
     strMap["_forceModelIngredientAcqForA_"] = ingredient_acquisition_A;
     strMap["_forceModelIngredientAcqForB_"] = ingredient_acquisition_B;

{deme-2.0.3 → deme-2.0.5}/src/DEM/APIPublic.cpp

@@ -213,7 +213,7 @@ void DEMSolver::SetContactOutputContent(const std::vector<std::string>& content)
                 m_cnt_out_content = m_cnt_out_content | CNT_OUTPUT_CONTENT::FORCE;
                 break;
             case ("POINT"_):
-                m_cnt_out_content = m_cnt_out_content | CNT_OUTPUT_CONTENT::DEME_POINT;
+                m_cnt_out_content = m_cnt_out_content | CNT_OUTPUT_CONTENT::CNT_POINT;
                 break;
             case ("COMPONENT"_):
                 m_cnt_out_content = m_cnt_out_content | CNT_OUTPUT_CONTENT::COMPONENT;
@@ -399,6 +399,68 @@ std::vector<std::pair<bodyID_t, bodyID_t>> DEMSolver::GetClumpContacts(
     return out_pair;
 }
 
+std::vector<std::pair<bodyID_t, bodyID_t>> DEMSolver::GetContacts() const {
+    std::vector<bodyID_t> idA_tmp, idB_tmp;
+    std::vector<family_t> famA_tmp, famB_tmp;
+    std::vector<contact_t> cnt_type_tmp;
+    // Getting sphere contacts is enough
+    getContacts_impl(idA_tmp, idB_tmp, cnt_type_tmp, famA_tmp, famB_tmp, [](contact_t type) { return true; });
+    auto idx = hostSortIndices(idA_tmp);
+    std::vector<std::pair<bodyID_t, bodyID_t>> out_pair(idx.size());
+    for (size_t i = 0; i < idx.size(); i++) {
+        out_pair[i] = std::pair<bodyID_t, bodyID_t>(idA_tmp[idx[i]], idB_tmp[idx[i]]);
+    }
+    return out_pair;
+}
+
+std::vector<std::pair<bodyID_t, bodyID_t>> DEMSolver::GetContacts(const std::set<family_t>& family_to_include) const {
+    std::vector<bodyID_t> idA_tmp, idB_tmp;
+    std::vector<family_t> famA_tmp, famB_tmp;
+    std::vector<contact_t> cnt_type_tmp;
+    // Getting sphere contacts is enough
+    getContacts_impl(idA_tmp, idB_tmp, cnt_type_tmp, famA_tmp, famB_tmp, [](contact_t type) { return true; });
+    // Exclude the families that are not in the set
+    std::vector<bool> elem_to_remove(idA_tmp.size(), false);
+    for (size_t i = 0; i < idA_tmp.size(); i++) {
+        if (!check_exist(family_to_include, famA_tmp.at(i)) || !check_exist(family_to_include, famB_tmp.at(i))) {
+            elem_to_remove[i] = true;
+        }
+    }
+    idA_tmp = hostRemoveElem(idA_tmp, elem_to_remove);
+    idB_tmp = hostRemoveElem(idB_tmp, elem_to_remove);
+    famA_tmp = hostRemoveElem(famA_tmp, elem_to_remove);
+    famB_tmp = hostRemoveElem(famB_tmp, elem_to_remove);
+    cnt_type_tmp = hostRemoveElem(cnt_type_tmp, elem_to_remove);
+
+    auto idx = hostSortIndices(idA_tmp);
+    std::vector<std::pair<bodyID_t, bodyID_t>> out_pair(idx.size());
+    for (size_t i = 0; i < idx.size(); i++) {
+        out_pair[i] = std::pair<bodyID_t, bodyID_t>(idA_tmp[idx[i]], idB_tmp[idx[i]]);
+    }
+    return out_pair;
+}
+
+std::vector<std::pair<bodyID_t, bodyID_t>> DEMSolver::GetContacts(
+    std::vector<std::pair<family_t, family_t>>& family_pair) const {
+    std::vector<bodyID_t> idA_tmp, idB_tmp;
+    std::vector<family_t> famA_tmp, famB_tmp;
+    std::vector<contact_t> cnt_type_tmp;
+    // Getting sphere contacts is enough
+    getContacts_impl(idA_tmp, idB_tmp, cnt_type_tmp, famA_tmp, famB_tmp, [](contact_t type) { return true; });
+    auto idx = hostSortIndices(idA_tmp);
+    std::vector<std::pair<bodyID_t, bodyID_t>> out_pair(idx.size());
+    family_pair.resize(idx.size());
+    for (size_t i = 0; i < idx.size(); i++) {
+        out_pair[i] = std::pair<bodyID_t, bodyID_t>(idA_tmp[idx[i]], idB_tmp[idx[i]]);
+        family_pair[i] = std::pair<family_t, family_t>(famA_tmp[idx[i]], famB_tmp[idx[i]]);
+    }
+    return out_pair;
+}
+
+std::shared_ptr<ContactInfoContainer> DEMSolver::GetContactDetailedInfo(float force_thres) const {
+    return dT->generateContactInfo(force_thres);
+}
+
 std::vector<float3> DEMSolver::GetOwnerPosition(bodyID_t ownerID, bodyID_t n) const {
     return dT->getOwnerPos(ownerID, n);
 }
@@ -2195,7 +2257,7 @@ void DEMSolver::UpdateSimParams() {
     std::thread dT_build([&]() {
         DEME_GPU_CALL(cudaSetDevice(dT->streamInfo.device));
         // Jitify max vel finder, in case the policy there changed
-        m_approx_max_vel_func->Initialize(m_subs, true);
+        m_approx_max_vel_func->Initialize(m_subs, m_jitify_options, true);
         dT->approxMaxVelFunc = m_approx_max_vel_func;
         // Updating sim environment is critical
         dT->announceCritical();

{deme-2.0.3 → deme-2.0.5}/src/DEM/AuxClasses.cpp

@@ -186,11 +186,13 @@ float* DEMInspector::dT_GetValue() {
 
 void DEMInspector::assertInit() {
     if (!initialized) {
-        Initialize(sys->GetJitStringSubs());
+        Initialize(sys->GetJitStringSubs(), sys->GetJitifyOptions());
     }
 }
 
-void DEMInspector::Initialize(const std::unordered_map<std::string, std::string>& Subs, bool force) {
+void DEMInspector::Initialize(const std::unordered_map<std::string, std::string>& Subs,
+                              const std::vector<std::string>& options,
+                              bool force) {
     if (!(sys->GetInitStatus()) && !force) {
         std::stringstream ss;
         ss << "Inspector should only be initialized or used after the simulation system is initialized (because it "
@@ -221,12 +223,11 @@ void DEMInspector::Initialize(const std::unordered_map<std::string, std::string>
     my_subs["_inRegionPolicy_"] = in_region_specifier;
     my_subs["_quantityQueryProcess_"] = inspection_code;
     if (thing_to_insp == INSPECT_ENTITY_TYPE::SPHERE) {
-        inspection_kernel = std::make_shared<jitify::Program>(std::move(
-            JitHelper::buildProgram("DEMSphereQueryKernels", JitHelper::KERNEL_DIR / "DEMSphereQueryKernels.cu",
-                                    my_subs, DEME_JITIFY_OPTIONS)));
+        inspection_kernel = std::make_shared<jitify::Program>(std::move(JitHelper::buildProgram(
+            "DEMSphereQueryKernels", JitHelper::KERNEL_DIR / "DEMSphereQueryKernels.cu", my_subs, options)));
     } else if (thing_to_insp == INSPECT_ENTITY_TYPE::CLUMP || thing_to_insp == INSPECT_ENTITY_TYPE::EVERYTHING) {
         inspection_kernel = std::make_shared<jitify::Program>(std::move(JitHelper::buildProgram(
-            "DEMOwnerQueryKernels", JitHelper::KERNEL_DIR / "DEMOwnerQueryKernels.cu", my_subs, DEME_JITIFY_OPTIONS)));
+            "DEMOwnerQueryKernels", JitHelper::KERNEL_DIR / "DEMOwnerQueryKernels.cu", my_subs, options)));
     } else {
         std::stringstream ss;
         ss << "Sorry, an inspector object you are using is not implemented yet.\nConsider letting the developers know "
@@ -926,6 +927,17 @@ int DEMForceModel::ReadCustomModelFile(const std::filesystem::path& sourcefile)
     return 0;
 }
 
+void DEMForceModel::DefineCustomModelPrerequisites(const std::string& util) {
+    m_model_prerequisites = util;
+}
+int DEMForceModel::ReadCustomModelPrerequisitesFile(const std::filesystem::path& sourcefile) {
+    if (!std::filesystem::exists(sourcefile)) {
+        return 1;
+    }
+    m_model_prerequisites = read_file_to_string(sourcefile);
+    return 0;
+}
+
 void DEMForceModel::SetPerContactWildcards(const std::set<std::string>& wildcards) {
     for (const auto& a_str : wildcards) {
         if (match_pattern(a_str, " ")) {

{deme-2.0.3 → deme-2.0.5}/src/DEM/AuxClasses.h

@@ -70,7 +70,9 @@ class DEMInspector {
     void SetInspectionCode(const std::string& code) { inspection_code = code; }
 
     // Initialize with the DEM simulation system (user should not call this)
-    void Initialize(const std::unordered_map<std::string, std::string>& Subs, bool force = false);
+    void Initialize(const std::unordered_map<std::string, std::string>& Subs,
+                    const std::vector<std::string>& options,
+                    bool force = false);
 
     /// Get the reduce value of the quantity that you wish to inspect.
     float GetValue();
@@ -434,6 +436,8 @@ class DEMForceModel {
     FORCE_MODEL type = FORCE_MODEL::CUSTOM;
     // The model
     std::string m_force_model = " ";
+    // Mainly for device util functions this model might need.
+    std::string m_model_prerequisites = " ";
     // Quatity names that we want to associate each contact pair with. An array will be allocated for storing this, and
     // it lives and die with contact pairs.
     std::set<std::string> m_contact_wildcards;
@@ -451,14 +455,20 @@ class DEMForceModel {
     DEMForceModel() {}
     ~DEMForceModel() {}
 
-    /// Set the contact force model type
+    /// Set the contact force model type.
     void SetForceModelType(FORCE_MODEL model_type);
-    /// Define user-custom force model with a string which is your force calculation code
+    /// Define user-custom force model with a string which is your force calculation code.
     void DefineCustomModel(const std::string& model);
     /// Read user-custom force model from a file (which by default should reside in kernel/DEMUserScripts), which
     /// contains your force calculation code. Returns 0 if read successfully, otherwise 1.
     int ReadCustomModelFile(const std::filesystem::path& sourcefile);
 
+    /// Define user-custom force model's utility __device__ functions with a string.
+    void DefineCustomModelPrerequisites(const std::string& util);
+    /// Read user-custom force model's utility __device__ functions from a file (which by default should reside in
+    /// kernel/DEMUserScripts). Returns 0 if read successfully, otherwise 1.
+    int ReadCustomModelPrerequisitesFile(const std::filesystem::path& sourcefile);
+
     /// @brief Specifiy the material properties that this force model will use.
     /// @param props Material property names.
     void SetMustHaveMatProp(const std::set<std::string>& props) { m_must_have_mat_props = props; }

{deme-2.0.3 → deme-2.0.5}/src/DEM/Defines.h

@@ -26,7 +26,7 @@ namespace deme {
 // It is better to keep DEME_NUM_SPHERES_PER_CD_BATCH == DEME_KT_CD_NTHREADS_PER_BLOCK for better performance
 #define DEME_NUM_SPHERES_PER_CD_BATCH 512    ///< Can't be larger than DEME_KT_CD_NTHREADS_PER_BLOCK
 #define DEME_NUM_TRIANGLES_PER_CD_BATCH 256  ///< Can't be larger than DEME_KT_CD_NTHREADS_PER_BLOCK
-#define DEME_TINY_FLOAT 1e-12
+#define DEME_TINY_FLOAT 1e-15
 #define DEME_HUGE_FLOAT 1e15
 #define DEME_BITS_PER_BYTE 8
 #define DEME_CUDA_WARP_SIZE 32
@@ -170,12 +170,12 @@ enum OUTPUT_CONTENT {
 enum class SPATIAL_DIR { X, Y, Z, NONE };
 // The info that should be present in the contact pair output files
 enum CNT_OUTPUT_CONTENT {
-    CNT_TYPE = 0,    // Owner numbers and contact type
-    FORCE = 1,       // Force (that owner 1 feels) xyz components in global
-    DEME_POINT = 2,  // Contact point in global frame
-    COMPONENT = 4,   // The component numbers (such as triangle number for a mesh) that involved in this contact
-    NORMAL = 8,      // Contact normal direction in global frame
-    TORQUE = 16,     // This is a standalone force and produces torque only (typical example: rolling resistance force)
+    CNT_TYPE = 0,   // Owner numbers and contact type
+    FORCE = 1,      // Force (that owner 1 feels) xyz components in global
+    CNT_POINT = 2,  // Contact point in global frame
+    COMPONENT = 4,  // The component numbers (such as triangle number for a mesh) that involved in this contact
+    NORMAL = 8,     // Contact normal direction in global frame
+    TORQUE = 16,    // This is a standalone force and produces torque only (typical example: rolling resistance force)
     CNT_WILDCARD = 32,
     OWNER = 64,
     GEO_ID = 128,

{deme-2.0.3 → deme-2.0.5}/src/DEM/PyDEME.cpp

@@ -205,6 +205,31 @@ PYBIND11_MODULE(DEME, obj) {
 
         .def("GetSeparation", &deme::HCPSampler::GetSeparation);
 
+    // Have to forward declare this templated method so pybind can see it
+    std::vector<float>& (deme::DataContainer::*get_float_dc)(const std::string&) = &deme::DataContainer::Get<float>;
+    py::class_<deme::DataContainer, std::shared_ptr<deme::DataContainer>>(obj, "DataContainer")
+        .def(py::init<>())
+        .def("Get", get_float_dc, py::return_value_policy::reference_internal,
+             "Get a float value from the container by name. Should be used for getting wildcard by name.");
+
+    py::class_<deme::ContactInfoContainer, deme::DataContainer, std::shared_ptr<deme::ContactInfoContainer>>(
+        obj, "ContactInfoContainer")
+        .def(py::init<unsigned int&, const std::vector<std::pair<std::string, std::string>>&>())
+        .def("GetContactType", &deme::ContactInfoContainer::GetContactType,
+             "Get contact type as strings from the container.")
+        .def("GetPoint", &deme::ContactInfoContainer::GetPoint, "Get contact points as vectors from the container.")
+        .def("GetAOwner", &deme::ContactInfoContainer::GetAOwner, "Get AOwner number from the container.")
+        .def("GetBOwner", &deme::ContactInfoContainer::GetBOwner, "Get BOwner number from the container.")
+        .def("GetAGeo", &deme::ContactInfoContainer::GetAGeo, "Get AGeo number from the container.")
+        .def("GetBGeo", &deme::ContactInfoContainer::GetBGeo, "Get BGeo number from the container.")
+        .def("GetAOwnerFamily", &deme::ContactInfoContainer::GetAOwnerFamily,
+             "Get AOwnerFamily number from the container.")
+        .def("GetBOwnerFamily", &deme::ContactInfoContainer::GetBOwnerFamily,
+             "Get BOwnerFamily number from the container.")
+        .def("GetForce", &deme::ContactInfoContainer::GetForce, "Get force as vectors from the container.")
+        .def("GetTorque", &deme::ContactInfoContainer::GetTorque, "Get torque as vectors from the container.")
+        .def("GetNormal", &deme::ContactInfoContainer::GetNormal, "Get contact normal as vectors from the container.");
+
     py::class_<deme::DEMInspector, std::shared_ptr<deme::DEMInspector>>(obj, "DEMInspector")
         .def(py::init<deme::DEMSolver*, deme::DEMDynamicThread*, const std::string&>())
         .def("GetValue", &deme::DEMInspector::GetValue);
@@ -417,11 +442,18 @@ PYBIND11_MODULE(DEME, obj) {
     py::class_<deme::DEMForceModel, std::shared_ptr<deme::DEMForceModel>>(obj, "DEMForceModel")
         .def(py::init<deme::FORCE_MODEL>())
         .def("SetForceModelType", &deme::DEMForceModel::SetForceModelType, "Set the contact force model type")
+
         .def("DefineCustomModel", &deme::DEMForceModel::DefineCustomModel,
-             "Define user-custom force model with a string which is your force calculation code")
+             "Define user-custom force model with a string which is your force calculation code.")
         .def("ReadCustomModelFile", &deme::DEMForceModel::ReadCustomModelFile,
              "Read user-custom force model from a file (which by default should reside in kernel/DEMUserScripts), "
              "which contains your force calculation code. Returns 0 if read successfully, otherwise 1.")
+        .def("DefineCustomModelPrerequisites", &deme::DEMForceModel::DefineCustomModelPrerequisites,
+             "Define user-custom force model's utility __device__ functions with a string.")
+        .def("ReadCustomModelPrerequisitesFile", &deme::DEMForceModel::ReadCustomModelPrerequisitesFile,
+             "Read user-custom force model's utility __device__ functions from a file (which by default should reside "
+             "in kernel/DEMUserScripts). Returns 0 if read successfully, otherwise 1.")
+
         .def("SetMustHaveMatProp", &deme::DEMForceModel::SetMustHaveMatProp,
              "Specifiy the material properties that this force model will use")
         .def("SetMustPairwiseMatProp", &deme::DEMForceModel::SetMustPairwiseMatProp,
@@ -491,6 +523,10 @@ PYBIND11_MODULE(DEME, obj) {
         .def("GetJitStringSubs", &deme::DEMSolver::GetJitStringSubs,
              "Get the jitification string substitution laundary list. It is needed by some of this simulation system's "
              "friend classes.")
+        .def("GetJitifyOptions", &deme::DEMSolver::GetJitifyOptions,
+             "Get current jitification options. It is needed by some of this simulation system's friend classes.")
+        .def("SetJitifyOptions", &deme::DEMSolver::SetJitifyOptions,
+             "Set the jitification options. It is only needed by advanced users.")
 
         .def("SetInitBinSizeAsMultipleOfSmallestSphere", &deme::DEMSolver::SetInitBinSizeAsMultipleOfSmallestSphere,
              "Explicitly instruct the bin size (for contact detection) that the solver should use, as a multiple of "
@@ -748,17 +784,50 @@ PYBIND11_MODULE(DEME, obj) {
         .def("GetClumpContacts",
              static_cast<std::vector<std::pair<deme::bodyID_t, deme::bodyID_t>> (deme::DEMSolver::*)() const>(
                  &deme::DEMSolver::GetClumpContacts),
-             "Get all clump--clump contacts in the simulation system.")
-
+             "Get all clump--clump contact ID pairs in the simulation system. Note all GetContact-like methods reports "
+             "potential contacts (not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.")
         .def("GetClumpContacts",
              static_cast<std::vector<std::pair<deme::bodyID_t, deme::bodyID_t>> (deme::DEMSolver::*)(
                  const std::set<deme::family_t>&) const>(&deme::DEMSolver::GetClumpContacts),
-             "Get all clump--clump contacts in the simulation system.")
-
+             "Get all clump--clump contact ID pairs in the simulation system. Note all GetContact-like methods reports "
+             "potential contacts (not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does. Use the argument to "
+             "include only these families in the output.")
         .def("GetClumpContacts",
              static_cast<std::vector<std::pair<deme::bodyID_t, deme::bodyID_t>> (deme::DEMSolver::*)(
                  std::vector<std::pair<deme::family_t, deme::family_t>>&) const>(&deme::DEMSolver::GetClumpContacts),
-             "Get all clump--clump contacts in the simulation system.")
+             "Get all clump--clump contact ID pairs in the simulation system. Note all GetContact-like methods reports "
+             "potential contacts (not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.")
+
+        .def("GetContacts",
+             static_cast<std::vector<std::pair<deme::bodyID_t, deme::bodyID_t>> (deme::DEMSolver::*)() const>(
+                 &deme::DEMSolver::GetContacts),
+             "Get all contact ID pairs in the simulation system. Note all GetContact-like methods reports potential "
+             "contacts (not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.")
+        .def("GetContacts",
+             static_cast<std::vector<std::pair<deme::bodyID_t, deme::bodyID_t>> (deme::DEMSolver::*)(
+                 const std::set<deme::family_t>&) const>(&deme::DEMSolver::GetContacts),
+             "Get all contact ID pairs in the simulation system. Note all GetContact-like methods reports potential "
+             "contacts (not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does. Use the argument to "
+             "include only these families in the output.")
+        .def("GetContacts",
+             static_cast<std::vector<std::pair<deme::bodyID_t, deme::bodyID_t>> (deme::DEMSolver::*)(
+                 std::vector<std::pair<deme::family_t, deme::family_t>>&) const>(&deme::DEMSolver::GetContacts),
+             "Get all contact ID pairs in the simulation system. Note all GetContact-like methods reports potential "
+             "contacts (not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.")
+
+        .def("GetContactDetailedInfo", &deme::DEMSolver::GetContactDetailedInfo,
+             "Get all contact pairs' detailed information (actual content based on the setting with "
+             "SetContactOutputContent; default are owner IDs, contact point location, contact force, and associated "
+             "wildcard values) in the simulation system. Note all GetContact-like methods reports potential contacts "
+             "(not necessarily confirmed contacts), meaning they are similar to what "
+             "WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.",
+             py::arg("force_thres") = -1.0)
 
         .def("GetHostMemUsageDynamic", &deme::DEMSolver::GetHostMemUsageDynamic,
              "Get the host memory usage (in bytes) on dT.")
@@ -948,6 +1017,18 @@ PYBIND11_MODULE(DEME, obj) {
         .def("SetAnalWildcardValue", &deme::DEMSolver::SetAnalWildcardValue,
              "Set the wildcard values of some analytical components.")
 
+        .def("SetOwnerWildcardValue",
+             static_cast<void (deme::DEMSolver::*)(deme::bodyID_t ownerID, const std::string& name,
+                                                   const std::vector<float>& vals)>(
+                 &deme::DEMSolver::SetOwnerWildcardValue),
+             "Set the wildcard values of some owners using a list.", py::arg("ownerIDs"), py::arg("name"),
+             py::arg("vals"))
+        .def("SetOwnerWildcardValue",
+             static_cast<void (deme::DEMSolver::*)(deme::bodyID_t ownerID, const std::string& name, float val,
+                                                   size_t n)>(&deme::DEMSolver::SetOwnerWildcardValue),
+             "Set the wildcard values of some owners using a list.", py::arg("ownerIDs"), py::arg("name"),
+             py::arg("val"), py::arg("n") = 1)
+
         .def("GetOwnerWildcardValue",
              static_cast<std::vector<float> (deme::DEMSolver::*)(deme::bodyID_t ownerID, const std::string& name,
                                                                  deme::bodyID_t n)>(
@@ -987,11 +1068,6 @@ PYBIND11_MODULE(DEME, obj) {
              "Add an extra contact margin to entities in a family so they are registered as potential contact pairs "
              "earlier.")
 
-        .def("GetAllOwnerWildcardValue", &deme::DEMSolver::GetAllOwnerWildcardValue,
-             "Get the owner wildcard's values of all entities.")
-        .def("GetFamilyOwnerWildcardValue", &deme::DEMSolver::GetFamilyOwnerWildcardValue,
-             "Get the owner wildcard's values of all entities in family N.")
-
         .def("ClearCache", &deme::DEMSolver::ClearCache,
              "Remove host-side cached vectors (so you can re-define them, and then re-initialize system).")
 
@@ -1000,7 +1076,11 @@ PYBIND11_MODULE(DEME, obj) {
                  &deme::DEMSolver::CreateInspector),
              "Create a inspector object that can help query some statistical info of the clumps in the simulation.",
              py::arg("quantity") = "clump_max_z")
-        .def("GetNumClumps", &deme::DEMSolver::GetNumClumps)
+        .def("GetNumClumps", &deme::DEMSolver::GetNumClumps,
+             "Return the number of clumps that are currently in the simulation. Must be used after initialization.")
+        .def("GetNumOwners", &deme::DEMSolver::GetNumOwners,
+             "Return the total number of owners (clumps + meshes + analytical objects) that are currently in the "
+             "simulation. Must be used after initialization.")
         .def("CreateInspector",
              static_cast<std::shared_ptr<deme::DEMInspector> (deme::DEMSolver::*)(
                  const std::string&, const std::string&)>(&deme::DEMSolver::CreateInspector),
@@ -1036,7 +1116,14 @@ PYBIND11_MODULE(DEME, obj) {
             "WriteContactFile",
             static_cast<void (deme::DEMSolver::*)(const std::string&, float) const>(&deme::DEMSolver::WriteContactFile),
             "Write all contact pairs to a file. Forces smaller than threshold will not be outputted.",
-            py::arg("outfilename"), py::arg("force_thres") = 1e-15)
+            py::arg("outfilename"), py::arg("force_thres") = 1e-30)
+        .def("WriteContactFileIncludingPotentialPairs",
+             static_cast<void (deme::DEMSolver::*)(const std::string&) const>(
+                 &deme::DEMSolver::WriteContactFileIncludingPotentialPairs),
+             "Write all contact pairs kT-supplied to a file, thus including the potential ones (those are not yet in "
+             "contact, or recently used to be in contact).",
+             py::arg("outfilename"))
+
         // Maybe add checkpoint-reading methods here...
         .def("DoDynamics", &deme::DEMSolver::DoDynamics,
              "Advance simulation by this amount of time (but does not attempt to sync kT and dT). This can work with "
@@ -1336,7 +1423,7 @@ PYBIND11_MODULE(DEME, obj) {
     py::enum_<deme::CNT_OUTPUT_CONTENT>(obj, "CNT_OUTPUT_CONTENT")
         .value("CNT_TYPE", deme::CNT_OUTPUT_CONTENT::CNT_TYPE)
         .value("FORCE", deme::CNT_OUTPUT_CONTENT::FORCE)
-        .value("POINT", deme::CNT_OUTPUT_CONTENT::DEME_POINT)
+        .value("POINT", deme::CNT_OUTPUT_CONTENT::CNT_POINT)
         .value("COMPONENT", deme::CNT_OUTPUT_CONTENT::COMPONENT)
         .value("NORMAL", deme::CNT_OUTPUT_CONTENT::NORMAL)
         .value("TORQUE", deme::CNT_OUTPUT_CONTENT::TORQUE)