Dynamically allocate contact and efc_ arrays on a new memory arena.

- Add private function `mj_arenaAlloc`. This is used internally to allocate memory from the arena.

- Add private function `mj_nefc` to count constraints. This function returns a tight upper bound on `d->nefc`. The number of counted constraints can be slightly bigger than exact `d->nefc` in the case of constraints with empty Jacobian, as when placing a frictional tendon between two world sites.

- Add new `memory` attribute to the `size` XML element for specification of arena memory size. This attribute is mutually exclusive with `nstack` and `njmax` specifications, which are now deprecated (but left around for the time being for legacy compatibility).

- Move `d->stack` to the end of the new arena space. The stack now grows in reverse from the end.

PiperOrigin-RevId: 479341539
Change-Id: Ie019c202e0908577ffc6f833a37920858116f667

doc/XMLreference.rst

@@ -479,7 +479,7 @@ from its default.
    This flag enables the simulation of sensor noise. When disabled (which is the default) noise is not added to
    sensordata, even if the sensors specify non-zero noise amplitudes. When enabled, zero-mean Gaussian noise is added to
    the underlying deterministic sensor data. Its standard deviation is determined by the noise parameter of each sensor.
-:at:`multiccd`: :at-val:`[disable, enable], "disable"`             **(experimental feature)**
+:at:`multiccd`: :at-val:`[disable, enable], "disable"` |nbsp| |nbsp| |nbsp| (experimental feature)
    This flag enables multiple-contact collision detection for geom pairs that use the general-purpose convex-convex
    collider based on :ref:`libccd <coChecking>` e.g., mesh-mesh collisions. This can be useful when the contacting geoms
    have a flat surface, and the single contact point generated by the convex-convex collider cannot accurately capture
@@ -497,29 +497,25 @@ This element specifies size parameters that cannot be inferred from the number o
 fields of mjOption which can be modified at runtime, sizes are structural parameters and should not be modified after
 compilation.
 
-:at:`njmax`: :at-val:`int, "-1"`
-   This and the next two attributes specify the maximum sizes of the dynamic arrays in mjData, i.e., arrays whose
-   effective length varies at runtime. This attribute specifies the maximum number of scalar constraints (or
-   equivalently, rows of the constraint Jacobian) that can be handled at runtime. If the number of active constraints is
-   about to exceed this maximum (usually because too many contacts become active) the extra constraints are discarded
-   and a warning is generated. The number of active constraints is stored in mjData.nefc. The default setting of -1
-   instructs the compiler to guess how much space to allocate (using heuristics that can be improved). This default is
-   effectively an undefined state. If the user specifies a positive value, the compiler heuristics are disabled and the
-   specified value is used. Modern computers have sufficient memory to handle very large models (larger than one would
-   normally have the patience to simulate) so tuning this setting aggressively is not necessary. When size-related
-   warnings or errors are generated, simply increase the value of the corresponding attribute.
-:at:`nconmax`: :at-val:`int, "-1"`
-   This attribute specifies the maximum number of contacts (both frictional and frictionless) that can be handled at
-   runtime. If the number of active contacts is about to exceed this value, the extra contacts are discarded and a
-   warning is generated. The actual number of contacts is stored in mjData.ncon. If this value is negative, the compiler
-   will use a heuristic to guess an appropriate number.
-:at:`nstack`: :at-val:`int, "-1"`
-   This attribute specifies the size of the preallocated stack in mjData, in units of sizeof(mjtNum) which is currently
-   defined as double; thus the size in bytes is 8 times larger. The custom stack is used by all MuJoCo functions that
-   need dynamically allocated memory. We do not use heap memory allocation at runtime, so as to speed up processing as
-   well as avoid heap fragmentation. Note that the internal allocator keeps track of how much stack space has ever been
-   utilized, in the field mjData.maxstackuse of mjData. If the stack size is exceeded at runtime, MuJoCo will generate
-   an error. If this value is negative, the compiler will use a heuristic to guess an appropriate number.
+:at:`memory`: :at-val:`string, "-1"`
+   This attribute specifies the size of memory allocated for dynamic arrays in the ``mjData.arena`` memory space, in
+   bytes. The default setting of ``-1`` instructs the compiler to guess how much space to allocate. Appending the digits
+   with one of the letters {K, M, G, T, P, E} sets the unit to be {kilo, mega, giga, tera, peta, exa}-byte,
+   respectively. Thus "16M" means "allocate 16 megabytes of ``arena`` memory".
+   See the :ref:`Memory allocation <CSize>` section for details.
+:at:`njmax`: :at-val:`int, "-1"` |nbsp| |nbsp| |nbsp| (legacy)
+   This is a deprecated legacy attribute. In versions prior to 2.3.0, it determined the maximum allowed number
+   of constraints. Currently it means "allocate as much memory as would have previously been required for this number of
+   constraints". Specifying both :at:`njmax` and :at:`memory` leads to an error.
+:at:`nconmax`: :at-val:`int, "-1"` |nbsp| |nbsp| |nbsp| (legacy)
+   This attribute specifies the maximum number of contacts that will be generated at runtime.  If the number of active
+   contacts is about to exceed this value, the extra contacts are discarded and a warning is generated.  This is a
+   deprecated legacy attribute which prior to version 2.3.0 affected memory allocation. It is kept for backwards
+   compatibillity and debugging purposes.
+:at:`nstack`: :at-val:`int, "-1"` |nbsp| |nbsp| |nbsp| (legacy)
+   This is a deprecated legacy attribute. In versions prior to 2.3.0, it determined the maximum size of the
+   :ref:`stack <siStack>`. Currently it is synonymous with the :at:`memory` attribute above, but is in units of
+   ``sizeof(mjtNum)`` rather than bytes. Specifying both :at:`nstack` and :at:`memory` leads to an error.
 :at:`nuserdata`: :at-val:`int, "0"`
    The size of the field mjData.userdata of mjData. This field should be used to store custom dynamic variables. See
    also :ref:`CUser`.