From ca44ad4f0f35d2c01b53b942c00f49a6ae0175a7 Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Wed, 3 Jul 2024 14:14:44 -0700 Subject: [PATCH] Improve docstrings and layout in mjdata.h PiperOrigin-RevId: 649195756 Change-Id: Iadf6589c226acacd9f3e85959de552a98fc7435a --- doc/includes/references.h | 42 ++++++++++++------------ include/mujoco/mjdata.h | 42 ++++++++++++------------ introspect/structs.py | 48 ++++++++++++++-------------- unity/Runtime/Bindings/MjBindings.cs | 46 +++++++++++++------------- 4 files changed, 89 insertions(+), 89 deletions(-) diff --git a/doc/includes/references.h b/doc/includes/references.h index 27e54dbb..1d2c724e 100644 --- a/doc/includes/references.h +++ b/doc/includes/references.h @@ -139,29 +139,29 @@ struct mjData_ { int nplugin; // number of plugin instances // stack pointer - size_t pstack; // first available mjtNum address in stack + size_t pstack; // first available byte in stack size_t pbase; // value of pstack when mj_markStack was last called // arena pointer size_t parena; // first available byte in arena - // memory utilization stats - size_t maxuse_stack; // maximum stack allocation in bytes - size_t maxuse_threadstack[mjMAXTHREAD]; // maximum stack allocation per thread in bytes - size_t maxuse_arena; // maximum arena allocation in bytes - int maxuse_con; // maximum number of contacts - int maxuse_efc; // maximum number of scalar constraints - - // diagnostics - mjWarningStat warning[mjNWARNING]; // warning statistics - mjTimerStat timer[mjNTIMER]; // timer statistics + // memory utilization statistics + size_t maxuse_stack; // maximum stack allocation in bytes + size_t maxuse_threadstack[mjMAXTHREAD]; // maximum stack allocation per thread in bytes + size_t maxuse_arena; // maximum arena allocation in bytes + int maxuse_con; // maximum number of contacts + int maxuse_efc; // maximum number of scalar constraints // solver statistics mjSolverStat solver[mjNISLAND*mjNSOLVER]; // solver statistics per island, per iteration - int solver_nisland; // number of islands processed by solver - int solver_niter[mjNISLAND]; // number of solver iterations, per island - int solver_nnz[mjNISLAND]; // number of non-zeros in Hessian or efc_AR, per island - mjtNum solver_fwdinv[2]; // forward-inverse comparison: qfrc, efc + int solver_nisland; // number of islands processed by solver + int solver_niter[mjNISLAND]; // number of solver iterations, per island + int solver_nnz[mjNISLAND]; // number of nonzeros in Hessian or efc_AR, per island + mjtNum solver_fwdinv[2]; // forward-inverse comparison: qfrc, efc + + // diagnostics + mjWarningStat warning[mjNWARNING]; // warning statistics + mjTimerStat timer[mjNTIMER]; // timer statistics // variable sizes int ne; // number of equality constraints @@ -274,7 +274,7 @@ struct mjData_ { // computed by mj_collisionTree mjtNum* bvh_aabb_dyn; // global bounding box (center, size) (nbvhdynamic x 6) - mjtByte* bvh_active; // volume has been added to collisions (nbvh x 1) + mjtByte* bvh_active; // was bounding volume checked for collision (nbvh x 1) //-------------------- POSITION, VELOCITY dependent @@ -344,7 +344,7 @@ struct mjData_ { //-------------------- arena-allocated: POSITION dependent // computed by mj_collision - mjContact* contact; // list of all detected contacts (ncon x 1) + mjContact* contact; // array of all detected contacts (ncon x 1) // computed by mj_makeConstraint int* efc_type; // constraint type (mjtConstraint) (nefc x 1) @@ -394,11 +394,11 @@ struct mjData_ { //-------------------- arena-allocated: POSITION, VELOCITY, CONTROL/ACCELERATION dependent // computed by mj_fwdConstraint/mj_inverse - mjtNum* efc_b; // linear cost term: J*qacc_smooth - aref (nefc x 1) - mjtNum* efc_force; // constraint force in constraint space (nefc x 1) - int* efc_state; // constraint state (mjtConstraintState) (nefc x 1) + mjtNum* efc_b; // linear cost term: J*qacc_smooth - aref (nefc x 1) + mjtNum* efc_force; // constraint force in constraint space (nefc x 1) + int* efc_state; // constraint state (mjtConstraintState) (nefc x 1) - // ThreadPool for multithreaded operations + // thread pool pointer uintptr_t threadpool; }; typedef struct mjData_ mjData; diff --git a/include/mujoco/mjdata.h b/include/mujoco/mjdata.h index 7c5ecb50..45c8229e 100644 --- a/include/mujoco/mjdata.h +++ b/include/mujoco/mjdata.h @@ -167,29 +167,29 @@ struct mjData_ { int nplugin; // number of plugin instances // stack pointer - size_t pstack; // first available mjtNum address in stack + size_t pstack; // first available byte in stack size_t pbase; // value of pstack when mj_markStack was last called // arena pointer size_t parena; // first available byte in arena - // memory utilization stats - size_t maxuse_stack; // maximum stack allocation in bytes - size_t maxuse_threadstack[mjMAXTHREAD]; // maximum stack allocation per thread in bytes - size_t maxuse_arena; // maximum arena allocation in bytes - int maxuse_con; // maximum number of contacts - int maxuse_efc; // maximum number of scalar constraints - - // diagnostics - mjWarningStat warning[mjNWARNING]; // warning statistics - mjTimerStat timer[mjNTIMER]; // timer statistics + // memory utilization statistics + size_t maxuse_stack; // maximum stack allocation in bytes + size_t maxuse_threadstack[mjMAXTHREAD]; // maximum stack allocation per thread in bytes + size_t maxuse_arena; // maximum arena allocation in bytes + int maxuse_con; // maximum number of contacts + int maxuse_efc; // maximum number of scalar constraints // solver statistics mjSolverStat solver[mjNISLAND*mjNSOLVER]; // solver statistics per island, per iteration - int solver_nisland; // number of islands processed by solver - int solver_niter[mjNISLAND]; // number of solver iterations, per island - int solver_nnz[mjNISLAND]; // number of non-zeros in Hessian or efc_AR, per island - mjtNum solver_fwdinv[2]; // forward-inverse comparison: qfrc, efc + int solver_nisland; // number of islands processed by solver + int solver_niter[mjNISLAND]; // number of solver iterations, per island + int solver_nnz[mjNISLAND]; // number of nonzeros in Hessian or efc_AR, per island + mjtNum solver_fwdinv[2]; // forward-inverse comparison: qfrc, efc + + // diagnostics + mjWarningStat warning[mjNWARNING]; // warning statistics + mjTimerStat timer[mjNTIMER]; // timer statistics // variable sizes int ne; // number of equality constraints @@ -302,7 +302,7 @@ struct mjData_ { // computed by mj_collisionTree mjtNum* bvh_aabb_dyn; // global bounding box (center, size) (nbvhdynamic x 6) - mjtByte* bvh_active; // volume has been added to collisions (nbvh x 1) + mjtByte* bvh_active; // was bounding volume checked for collision (nbvh x 1) //-------------------- POSITION, VELOCITY dependent @@ -372,7 +372,7 @@ struct mjData_ { //-------------------- arena-allocated: POSITION dependent // computed by mj_collision - mjContact* contact; // list of all detected contacts (ncon x 1) + mjContact* contact; // array of all detected contacts (ncon x 1) // computed by mj_makeConstraint int* efc_type; // constraint type (mjtConstraint) (nefc x 1) @@ -422,11 +422,11 @@ struct mjData_ { //-------------------- arena-allocated: POSITION, VELOCITY, CONTROL/ACCELERATION dependent // computed by mj_fwdConstraint/mj_inverse - mjtNum* efc_b; // linear cost term: J*qacc_smooth - aref (nefc x 1) - mjtNum* efc_force; // constraint force in constraint space (nefc x 1) - int* efc_state; // constraint state (mjtConstraintState) (nefc x 1) + mjtNum* efc_b; // linear cost term: J*qacc_smooth - aref (nefc x 1) + mjtNum* efc_force; // constraint force in constraint space (nefc x 1) + int* efc_state; // constraint state (mjtConstraintState) (nefc x 1) - // ThreadPool for multithreaded operations + // thread pool pointer uintptr_t threadpool; }; typedef struct mjData_ mjData; diff --git a/introspect/structs.py b/introspect/structs.py index 8fa8790b..180ed135 100644 --- a/introspect/structs.py +++ b/introspect/structs.py @@ -4183,7 +4183,7 @@ STRUCTS: Mapping[str, StructDecl] = dict([ StructFieldDecl( name='pstack', type=ValueType(name='size_t'), - doc='first available mjtNum address in stack', + doc='first available byte in stack', ), StructFieldDecl( name='pbase', @@ -4223,22 +4223,6 @@ STRUCTS: Mapping[str, StructDecl] = dict([ type=ValueType(name='int'), doc='maximum number of scalar constraints', ), - StructFieldDecl( - name='warning', - type=ArrayType( - inner_type=ValueType(name='mjWarningStat'), - extents=(8,), - ), - doc='warning statistics', - ), - StructFieldDecl( - name='timer', - type=ArrayType( - inner_type=ValueType(name='mjTimerStat'), - extents=(15,), - ), - doc='timer statistics', - ), StructFieldDecl( name='solver', type=ArrayType( @@ -4266,7 +4250,7 @@ STRUCTS: Mapping[str, StructDecl] = dict([ inner_type=ValueType(name='int'), extents=(20,), ), - doc='number of non-zeros in Hessian or efc_AR, per island', + doc='number of nonzeros in Hessian or efc_AR, per island', ), StructFieldDecl( name='solver_fwdinv', @@ -4276,6 +4260,22 @@ STRUCTS: Mapping[str, StructDecl] = dict([ ), doc='forward-inverse comparison: qfrc, efc', ), + StructFieldDecl( + name='warning', + type=ArrayType( + inner_type=ValueType(name='mjWarningStat'), + extents=(8,), + ), + doc='warning statistics', + ), + StructFieldDecl( + name='timer', + type=ArrayType( + inner_type=ValueType(name='mjTimerStat'), + extents=(15,), + ), + doc='timer statistics', + ), StructFieldDecl( name='ne', type=ValueType(name='int'), @@ -4756,7 +4756,7 @@ STRUCTS: Mapping[str, StructDecl] = dict([ type=PointerType( inner_type=ValueType(name='mjtByte'), ), - doc='volume has been added to collisions (nbvh x 1)', # pylint: disable=line-too-long + doc='was bounding volume checked for collision (nbvh x 1)', # pylint: disable=line-too-long ), StructFieldDecl( name='flexedge_velocity', @@ -4987,7 +4987,7 @@ STRUCTS: Mapping[str, StructDecl] = dict([ type=PointerType( inner_type=ValueType(name='mjContact'), ), - doc='list of all detected contacts (ncon x 1)', # pylint: disable=line-too-long + doc='array of all detected contacts (ncon x 1)', # pylint: disable=line-too-long ), StructFieldDecl( name='efc_type', @@ -5239,26 +5239,26 @@ STRUCTS: Mapping[str, StructDecl] = dict([ type=PointerType( inner_type=ValueType(name='mjtNum'), ), - doc='linear cost term: J*qacc_smooth - aref (nefc x 1)', # pylint: disable=line-too-long + doc='linear cost term: J*qacc_smooth - aref (nefc x 1)', # pylint: disable=line-too-long ), StructFieldDecl( name='efc_force', type=PointerType( inner_type=ValueType(name='mjtNum'), ), - doc='constraint force in constraint space (nefc x 1)', # pylint: disable=line-too-long + doc='constraint force in constraint space (nefc x 1)', # pylint: disable=line-too-long ), StructFieldDecl( name='efc_state', type=PointerType( inner_type=ValueType(name='int'), ), - doc='constraint state (mjtConstraintState) (nefc x 1)', # pylint: disable=line-too-long + doc='constraint state (mjtConstraintState) (nefc x 1)', # pylint: disable=line-too-long ), StructFieldDecl( name='threadpool', type=ValueType(name='uintptr_t'), - doc='ThreadPool for multithreaded operations', + doc='thread pool pointer', ), ), )), diff --git a/unity/Runtime/Bindings/MjBindings.cs b/unity/Runtime/Bindings/MjBindings.cs index c505449b..861f75e2 100644 --- a/unity/Runtime/Bindings/MjBindings.cs +++ b/unity/Runtime/Bindings/MjBindings.cs @@ -789,29 +789,6 @@ public unsafe struct mjData_ { public UIntPtr maxuse_arena; public int maxuse_con; public int maxuse_efc; - public mjWarningStat_ warning0; - public mjWarningStat_ warning1; - public mjWarningStat_ warning2; - public mjWarningStat_ warning3; - public mjWarningStat_ warning4; - public mjWarningStat_ warning5; - public mjWarningStat_ warning6; - public mjWarningStat_ warning7; - public mjTimerStat_ timer0; - public mjTimerStat_ timer1; - public mjTimerStat_ timer2; - public mjTimerStat_ timer3; - public mjTimerStat_ timer4; - public mjTimerStat_ timer5; - public mjTimerStat_ timer6; - public mjTimerStat_ timer7; - public mjTimerStat_ timer8; - public mjTimerStat_ timer9; - public mjTimerStat_ timer10; - public mjTimerStat_ timer11; - public mjTimerStat_ timer12; - public mjTimerStat_ timer13; - public mjTimerStat_ timer14; public mjSolverStat_ solver0; public mjSolverStat_ solver1; public mjSolverStat_ solver2; @@ -4816,6 +4793,29 @@ public unsafe struct mjData_ { public fixed int solver_niter[20]; public fixed int solver_nnz[20]; public fixed double solver_fwdinv[2]; + public mjWarningStat_ warning0; + public mjWarningStat_ warning1; + public mjWarningStat_ warning2; + public mjWarningStat_ warning3; + public mjWarningStat_ warning4; + public mjWarningStat_ warning5; + public mjWarningStat_ warning6; + public mjWarningStat_ warning7; + public mjTimerStat_ timer0; + public mjTimerStat_ timer1; + public mjTimerStat_ timer2; + public mjTimerStat_ timer3; + public mjTimerStat_ timer4; + public mjTimerStat_ timer5; + public mjTimerStat_ timer6; + public mjTimerStat_ timer7; + public mjTimerStat_ timer8; + public mjTimerStat_ timer9; + public mjTimerStat_ timer10; + public mjTimerStat_ timer11; + public mjTimerStat_ timer12; + public mjTimerStat_ timer13; + public mjTimerStat_ timer14; public int ne; public int nf; public int nl;