📝 Document mem_x

Author: shnizzedy

docs/_sources/developer/nodes.rst

@@ -8,22 +8,23 @@ Nodes
 
 .. _n_cpus:
 
-.. warning::
-   A Nipype :py:class:`~nipype.pipeline.engine.nodes.Node` has an initialization parameter ``mem_gb`` that differs from the :doc:`commandline option </user/run/help>` ``--mem_gb``. While the commandline option is **a limit**, the Node initialization parameter is **an estimate** of the most memory that Node will consume when run. The Node parameter is not a limit; rather, this value is used to allocate system resources at runtime.
-   
-   Conversely, the commandline option ``--n_cpus`` is **a limit** and the Node initialization parameter ``n_procs`` is **also a limit** of the maximum number of threads a Node will be permmitted to consume.
-   
-   C-PAC automatically creates a JSON-like file called ``callback.log`` (via the function :py:func:`~CPAC.utils.monitoring.log_nodes_cb`) when running. This file includes for each Node:
-
-      * estimated memory,
-      * memory usage observed at runtime,
-      * specified maximum number of threads per Node, and
-      * threads used at runtime.
-   
-   The Nipype utility function :py:func:`~nipype.utils.draw_gantt_chart.log_to_dict` reads a log file generated by ``log_nodes_cb`` to a Python dictionary. 
-   
-   When a developer creates or modifies a Node in C-PAC, a ``mem_gb`` and ``n_procs`` argument should be provided unless the respective defaults of 0.2 and None (number of available system cores) are expected to be sufficient. When testing, the ``mem_gb`` and ``n_procs`` arguments should be adjusted if the observed memory and/or thread usage of a Node exceeds the estimate.
- 
+A Nipype :py:class:`~nipype.pipeline.engine.nodes.Node` has an initialization parameter ``mem_gb`` that differs from the :doc:`commandline option </user/run/help>` ``--mem_gb``. While the commandline option is **a limit**, the Node initialization parameter is **an estimate** of the most memory that Node will consume when run. The Node parameter is not a limit; rather, this value is used to allocate system resources at runtime.
+
+Conversely, the commandline option ``--n_cpus`` is **a limit** and the Node initialization parameter ``n_procs`` is **also a limit** of the maximum number of threads a Node will be permmitted to consume.
+
+C-PAC automatically creates a JSON-like file called ``callback.log`` (via the function :py:func:`~CPAC.utils.monitoring.log_nodes_cb`) when running. This file includes for each Node:
+
+   * estimated memory,
+   * memory usage observed at runtime,
+   * specified maximum number of threads per Node, and
+   * threads used at runtime.
+
+When a developer creates or modifies a Node in C-PAC, a ``mem_gb`` and ``n_procs`` argument should be provided unless the respective defaults of 0.2 and None (number of available system cores) are expected to be sufficient. When testing, the ``mem_gb`` and ``n_procs`` arguments should be adjusted if the observed memory and/or thread usage of a Node exceeds the estimate.
+
+For nodes that will use a varying amount of memory depending on the node's input data, the optional parameter ``mem_x`` takes a tuple of ``(multiplier, multiplicand)`` where ``multiplier`` is a number and ``multiplicand`` is the string name of the input to multiply such that the memory estimate returned by the ``mem_gb`` attribute is the ``mem_gb`` argument plus ``multiplier`` times ``x`` × ``y`` × ``z`` × ``t`` of the ``multiplicand`` file.
+
+.. note::
+   ``mem_x`` is a new parameter in C-PAC v1.8.1 and subject to change in future releases as we continue to `develop methods for setting data- and operation-dependent memory estimates <https://github.com/FCP-INDI/C-PAC/issues/1509>`_.
 
 .. autoclass:: CPAC.pipeline.nipype_pipeline_engine.Node
    :special-members: __init__
@@ -35,6 +36,13 @@ Nodes
    :members:
    :inherited-members:
 
+.. autoclass:: CPAC.pipeline.nipype_pipeline_engine.Workflow
+   :special-members: __init__
+   :members:
+   :inherited-members:
+
+The Nipype utility function :py:func:`~nipype.utils.draw_gantt_chart.log_to_dict` reads a log file generated by ``log_nodes_cb`` to a Python dictionary.
+
 .. autofunction:: CPAC.utils.monitoring.log_nodes_cb
 
 draw_gantt_chart