gfn.gym.chip_design
===================

.. py:module:: gfn.gym.chip_design

.. autoapi-nested-parse::

   GFlowNet environment for chip placement.



Classes
-------

.. autoapisummary::

   gfn.gym.chip_design.ChipDesign
   gfn.gym.chip_design.ChipDesignStates
   gfn.gym.chip_design.CostStats


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

.. py:class:: ChipDesign(netlist_file = SAMPLE_NETLIST_FILE, init_placement = SAMPLE_INIT_PLACEMENT, std_cell_placer_mode = 'fd', wirelength_weight = 1.0, density_weight = 1.0, congestion_weight = 0.5, device = None, debug = False, singularity_image = None, cd_finetune = True, reward_norm = None, reward_temper = 1.0, reward_norm_samples = 100, cost_stats = None)

   Bases: :py:obj:`gfn.env.DiscreteEnv`


   GFlowNet environment for chip placement.

   The state is a vector of length `n_macros`, where `state[i]` is the grid
   cell location of the i-th macro to be placed. Unplaced macros have a
   location of -1.

   Actions are integers from `0` to `n_grid_cells - 1`, representing the
   grid cell to place the current macro on. Action `n_grid_cells` is the
   exit action.


   .. py:attribute:: States
      :type:  type[ChipDesignStates]


   .. py:method:: __del__()


   .. py:method:: _apply_state_to_plc(state_tensor)

      Applies a single state tensor to the plc object.



   .. py:method:: _backward_step(states, actions)

      Wraps parent _backward_step and updates masks.



   .. py:method:: _estimate_cost_stats(n_samples)

      Estimates cost distribution from random placements.



   .. py:attribute:: _hard_macro_indices


   .. py:method:: _normalize_cost(cost)

      Applies reward normalization to a raw cost value.



   .. py:attribute:: _sorted_node_indices


   .. py:method:: _step(states, actions)

      Wraps parent _step and updates masks.



   .. py:method:: analytical_placer()

      Places standard cells using an analytical placer.



   .. py:method:: backward_step(states, actions)

      Performs a backward step in the environment.



   .. py:attribute:: cd_finetune
      :value: True



   .. py:method:: close()

      Closes the PlacementCost subprocess to free resources.



   .. py:attribute:: congestion_weight
      :value: 0.5



   .. py:attribute:: density_weight
      :value: 1.0



   .. py:method:: log_reward(final_states)

      Computes the log reward of the final states.



   .. py:method:: make_states_class()

      Creates the ChipDesignStates class.



   .. py:attribute:: n_grid_cells


   .. py:attribute:: n_macros


   .. py:attribute:: plc


   .. py:method:: reset(batch_shape, random = False, sink = False, seed = None, conditions = None)

      Resets the environment and computes initial masks.



   .. py:attribute:: reward_norm
      :value: None



   .. py:attribute:: reward_temper
      :value: 1.0



   .. py:attribute:: std_cell_placer_mode
      :value: 'fd'



   .. py:method:: step(states, actions)

      Performs a forward step in the environment.



   .. py:method:: update_masks(states)

      Updates the forward and backward masks of the states.



   .. py:attribute:: wirelength_weight
      :value: 1.0



.. py:class:: ChipDesignStates(tensor, current_node_idx = None, conditions = None, device = None, debug = False)

   Bases: :py:obj:`gfn.states.DiscreteStates`


   A class to represent the states of the chip design environment.


   .. py:method:: __getitem__(index)

      Gets a subset of the states.



   .. py:method:: __setitem__(index, value)

      Sets a subset of the states.



   .. py:method:: clone()

      Creates a copy of the states.



   .. py:attribute:: current_node_idx
      :value: None



   .. py:method:: extend(other)

      Extends the states with another states.



   .. py:attribute:: n_actions
      :type:  ClassVar[int]


   .. py:attribute:: s0
      :type:  ClassVar[torch.Tensor]


   .. py:attribute:: sf
      :type:  ClassVar[torch.Tensor]


   .. py:method:: stack(states)
      :classmethod:


      Stacks the states with another states.



   .. py:attribute:: state_shape
      :type:  ClassVar[tuple[int, Ellipsis]]


.. py:class:: CostStats

   Pre-computed cost statistics for a netlist.


   .. py:attribute:: mean
      :type:  float


   .. py:attribute:: min
      :type:  float


   .. py:method:: precompute(netlists, n_samples = 100, wirelength_weight = 1.0, density_weight = 1.0, congestion_weight = 0.5, singularity_image = None)
      :staticmethod:


      Pre-compute cost statistics for multiple netlists.

      :param netlists: List of ``(netlist_file, init_placement)`` tuples.
      :param n_samples: Number of random placements per netlist.
      :param wirelength_weight: Wirelength weight for cost computation.
      :param density_weight: Density weight for cost computation.
      :param congestion_weight: Congestion weight for cost computation.
      :param singularity_image: Optional singularity image path.

      :returns: Dict mapping netlist file paths to their ``CostStats``.



   .. py:attribute:: range
      :type:  float


   .. py:attribute:: std
      :type:  float