Ops properties
==============

Native Aidge operators expose predefined static **properties** that describe their 
intrinsic mathematical behavior, characteristics, capabilities, or constraints. 
These **properties** enable generic heuristics that rely on operator attributes 
rather than operator types, such as PTQ or other graph optimization techniques.

Additional properties can also be defined by users.


Overview
--------

Each operator is described using the following properties:

- ``scale_law``: describes how outputs scale with inputs;

  Only for ``Homogeneous`` ``scale_law``:

  - ``homogeneity_degree``: exponent vector describing scaling behavior;
  - ``scale_composition``: how scaling propagates across multiple inputs;

- ``parity``: symmetry under input negation;
- ``commutative``: whether input ordering affects result.

This taxonomy is designed for static analysis of deep learning graphs and quantization propagation.


Core Definitions
-----------------

``scale_law`` Property
~~~~~~~~~~~~~~~~~~~~~~

``Homogeneous``
  Operator satisfies:

  .. math::

     f(\lambda x) = \lambda^d f(x)

  or more generally the following scale-equivariance law:

  .. math::

     f(\lambda_1 x_1, \lambda_2 x_2, ...) = \phi(\lambda_1^{d_1}, \lambda_2^{d_2}, ...) f(x_1, x_2, ...)

  In this case, the ``homogeneity_degree`` property **must be** specified:

  ``homogeneity_degree``
      Vector :math:`(d_1, d_2, \ldots)` such that scaling input
      :math:`i` by :math:`\lambda_i` contributes a factor
      :math:`\lambda_i^{d_i}` to the output scale.

      Examples:

      - ``MatMul``: (1, 1)
      - ``Mul``: (1, 1)
      - ``Div``: (1, -1)
      - ``Reciprocal``: (-1)
      - ``Sqrt``: (0.5)
      - ``ArgMax``: (0)

``Affine``
   Linear transformation with bias terms breaking strict scaling.

``GeneralNonlinear``
   No consistent scaling law exists.



``scale_composition`` Property
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Defines how scaling propagates across multiple inputs.
This property **must only be** specified for multi-inputs operators with the 
``Homogeneous`` ``scale_law`` property.

.. math::

   f(\lambda_1 x_1, \lambda_2 x_2, ...) = \phi(\lambda_1^{d_1}, \lambda_2^{d_2}, ...) f(x_1, x_2, ...)

We assume a scalar scale per tensor.
The goal is to characterize the function :math:`\phi`.

``Product``
   Scaling multiplies across inputs.

   .. math::

      \phi(\lambda_1^{d_1}, \lambda_2^{d_2}, ...) = \lambda_1^{d_1} \lambda_2^{d_2} ...

   ``MatMul`` Example:

   .. math::

      Z = A B

   Scaling:

   .. math::

      Z' = f(\lambda_1 A, \lambda_2 B) = \lambda_1 \lambda_2 f(A, B)

      Z' = \lambda_1 A \lambda_2 B = \lambda_1 \lambda_2 A B

   Interpretation:
      The output scale is exactly the product of the inputs scale.


``Union``
   Output is formed by selecting, routing, or combining values without arithmetic accumulation.

   .. math::

      \phi(\lambda_1^{d_1}, \lambda_2^{d_2}, ...) \leq max(\lambda_1^{d_1}, \lambda_2^{d_2}, ...)

   ``Max`` Example:

   .. math::

      Z = max(A, B)

   The output magnitude is bounded by:

   .. math::

      Z' = max(\lambda_1 A, \lambda_2 B) \leq max(\lambda_1, \lambda_2) max(A, B)

   Interpretation:
      The output scale estimate is :math:`max(\lambda_1, \lambda_2)`. If the inputs scale are homogeneous, the scale composition :math:`\phi` is exactly the maximum of the inputs scale.


``SumBound``
   Output is formed by arithmetic accumulation of multiple inputs.

   ``Add`` / ``Sum`` Example:

   .. math::

      Z = sum(A, B)

   The output magnitude is bounded by:

   .. math::

      \|Z'\| \leq \lambda_1 \|A\| + \lambda_2 \|B\| \leq max(\lambda_1, \lambda_2) (\|A\| + \|B\|)

   Therefore:

   .. math::

      \phi(\lambda_1, \lambda_2) \le max(\lambda_1, \lambda_2)

   Interpretation:
     An output scale of :math:`max(\lambda_1, \lambda_2)` is a conservative upper bound.


``parity`` Property
~~~~~~~~~~~~~~~~~~~

``Even``
   :math:`f(-x) = f(x)`

``Odd``
   :math:`f(-x) = -f(x)`

Note: many operators are neither and should be treated as undefined parity.


``commutative`` Property
~~~~~~~~~~~~~~~~~~~~~~~~

Boolean flag indicating whether input ordering affects output.

- Present and True: :math:`f(a, b) = f(b, a)`
- Absent or False: order matters

Commutativity applies only to input-value semantics (:class:`aidge_core.InputCategory.Data`
/ :class:`aidge_core.InputCategory.OptionalData` input category), not indexing or layout.


Operators taxonomy
------------------

.. jinja:: properties
   :file: jinja/predefined_ops_props.jinja
   :header_char: =