ml_switcheroo.compiler.backends.sass.synthesizer
================================================

.. py:module:: ml_switcheroo.compiler.backends.sass.synthesizer

.. autoapi-nested-parse::

   SASS Synthesizer and Register Allocator.

   This module provides the "Middle-End" logic for the SASS compiler pipeline.
   It bridges the gap between high-level Abstract Logic (LogicalGraph)
   and low-level Physical Assembly (Instruction nodes/Registers).

   It contains:
   1.  **RegisterAllocator**: Map Symbolic Variables (e.g., 'x', 'bias') to
       Physical Registers (e.g., 'R0', 'R1').
   2.  **SassSynthesizer**:
       -   **Target Transformation (`from_graph`)**: Converts a topological logical graph
           into a linear list of SASS instructions. Supports 1:1 opcode mapping via
           semantics and 1:N expansion via Kernel Macros (e.g. Conv2d loops).
       -   **Source Transformation (`to_python`)**: Converts SASS AST nodes back into
           Python LibCST nodes for high-level analysis or documentation.
   3.  **SassBackend**: The CompilerBackend adapter for the Registry.



Attributes
----------

.. autoapisummary::

   ml_switcheroo.compiler.backends.sass.synthesizer.MAX_REGISTERS


Classes
-------

.. autoapisummary::

   ml_switcheroo.compiler.backends.sass.synthesizer.RegisterAllocator
   ml_switcheroo.compiler.backends.sass.synthesizer.SassSynthesizer
   ml_switcheroo.compiler.backends.sass.synthesizer.SassBackend


Module Contents
---------------

.. py:data:: MAX_REGISTERS
   :value: 255


.. py:class:: RegisterAllocator

   Manages the mapping between symbolic variable names and physical registers.

   Implements a simple linear allocation strategy (bump pointer). A more complex
   implementation would handle liveness analysis and register spilling, but this
   suffices for basic block translation.


   .. py:method:: get_register(var_name: str) -> ml_switcheroo.compiler.frontends.sass.nodes.Register

      Retrieves or allocates a register for a symbolic variable.

      If the variable has been seen before, returns the existing register mapping.
      If new, allocates the next available physical register.

      :param var_name: The logical identifier (e.g., 'input_1', 'bias').
      :type var_name: str

      :returns: A populated Register node (e.g., Register('R0')).
      :rtype: Register

      :raises ValueError: If the allocator runs out of physical registers (>255).



   .. py:method:: allocate_temp() -> ml_switcheroo.compiler.frontends.sass.nodes.Register

      Allocates a temporary anonymous register.

      Useful for intermediate calculations or immediate loading.

      :returns: A new physical register.
      :rtype: Register



   .. py:method:: reset() -> None

      Resets the allocator state.



.. py:class:: SassSynthesizer(semantics: ml_switcheroo.semantics.manager.SemanticsManager)

   Bidirectional transpiler component.

   Handles:
   1.  **Forward (Graph -> SASS)**: Synthesizes Assembly from Logical Graphs.
       Delegates high-level ops (Conv2d, Linear) to Macros, and low-level ops
       (Add, Mul) to Semantic Opcode Lookup.
   2.  **Reverse (SASS -> Python)**: Synthesizes Python AST from Assembly nodes.


   .. py:attribute:: semantics


   .. py:attribute:: allocator


   .. py:attribute:: macro_registry
      :type:  Dict[str, Callable]


   .. py:method:: from_graph(graph: ml_switcheroo.compiler.ir.LogicalGraph) -> List[ml_switcheroo.compiler.frontends.sass.nodes.SassNode]

      Converts a LogicalGraph into a list of SASS AST nodes.

      Process:
      1.  Sorts nodes topologically.
      2.  Traverses nodes.
      3.  For each node:
          a. Check if it matches a Macro (e.g. Conv2d). If so, expand kernel.
          b. If not, lookup abstract opcode mapping (e.g. `Add` -> `FADD`).
          c. Allocate/Resolve Input Registers.
          d. Allocate Output Register.
          e. Construct `Instruction` node.
      4.  Handles `Input` nodes by pre-allocating registers (Contract: R0, R1...).

      :param graph: The input computation graph.
      :type graph: LogicalGraph

      :returns: A structured list of assembly nodes.
      :rtype: List[SassNode]



   .. py:method:: to_python(sass_nodes: List[ml_switcheroo.compiler.frontends.sass.nodes.SassNode]) -> libcst.Module

      Converts SASS AST nodes into a Python source structure representation.

      Used for analysis or round-trip verification. Registers are treated as
      variables. Instructions map to function calls `sass.OPCODE(args)`.

      Structure:
          `R0 = sass.FADD(R1, R2)`

      :param sass_nodes: List of parsed SASS nodes.
      :type sass_nodes: List[SassNode]

      :returns: A LibCST module containing the Python representation.
      :rtype: cst.Module



.. py:class:: SassBackend(semantics: Optional[ml_switcheroo.semantics.manager.SemanticsManager] = None)

   Bases: :py:obj:`ml_switcheroo.compiler.backend.CompilerBackend`


   Compiler Backend implementation for NVIDIA SASS.
   Orchestrates the synthesis (Graph -> AST) and emission (AST -> Text).


   .. py:attribute:: synthesizer


   .. py:attribute:: emitter


   .. py:method:: compile(graph: ml_switcheroo.compiler.ir.LogicalGraph) -> str

      Compiles LogicalGraph to SASS Assembly string.

      :param graph: The intermediate representation.

      :returns: The SASS code.
      :rtype: str