Relative placement macro

[amin1377]

This PR adds support for user-defined relative-placement macros in VPR constraint files. These constraints fix the placement of groups of primitives relative to one another without assigning them absolute locations.

This allows users to preserve the internal geometry of a hand-optimized block, such as a DSP with its control logic, a bit-sliced datapath, or an IP block, while leaving the placer free to choose where the block is located on the device.

Syntax

A new <relative_macro_list> section is supported inside the existing VPR constraints file specified by --read_vpr_constraints, alongside <partition_list>:

<vpr_constraints tool_name="vpr">
    <relative_macro_list>
        <relative_macro name="dsp_with_ctrl_logic">
            <reference_group>
                <add_atom name_pattern="mult_36.out_reg"/>
            </reference_group>

            <relative_group
                x_offset="1"
                y_offset="0"
                sub_tile_offset="0">
                <add_atom
                    name_pattern="^ctrl_lut_[0-4]$"
                    is_regex="true"/>
            </relative_group>
        </relative_macro>
    </relative_macro_list>
</vpr_constraints>

Each macro contains one <reference_group>, which acts as the anchor, and one or more <relative_group> elements. The <add_atom> element uses the same matching semantics as <partition>.

The constraints affect both packing and placement.

Packing

• All atoms within a group are packed into a single cluster.
• Atoms from different groups cannot share a cluster.
• Unconstrained atoms may still be packed into a group’s cluster.

Placement

The clusters belonging to a relative macro form a rigid placement macro, similar to an architectural carry chain, but with support for heterogeneous block types.

Each group’s cluster must remain at its specified offset from the reference cluster during both initial placement and annealing. The final placement is validated, so a successful run guarantees that all relative-placement constraints were satisfied.

Full documentation, including the file-format reference and detailed semantics, is available in:

doc/src/vpr/relative_placement_constraints.rst

Limitations

• Offsets are exact and must be compatible with the device grid, including fixed column types and multi-row tile alignment. If no valid placement exists, placement fails after an exhaustive search.
• sub_tile_offset is required.
• layer_offset must currently be 0. Cross-die macros are rejected when the constraints are loaded. Both fields are reserved for future extensions.
• A cluster cannot belong to both a user-defined relative macro and an architectural carry chain. Supporting merged macros is left as future work.
• A group that cannot be packed into a single cluster, because it is too large or conflicts with pack patterns, causes a packing error after retries (hard constraint)
• Only the classic packer reliably supports these constraints (Support for AP will be implemented later)
• Rigid macros reduce annealer mobility. Some QoR degradation compared with an unconstrained run is expected, particularly as macro size and constraint coverage increase.

Testing

This PR adds:

• Unit tests for the relative-placement constraints data model.

• A new vtr_reg_strong task, strong_relative_placement, covering:

  • Mixed-type macros
  • Regular-expression matching
  • LUT–FF molecule interactions
  • End-to-end packing and placement

The implementation was also validated on Titan benchmarks using constraint sets derived from baseline placements.

Results:

• All constrained macros were placed at their exact requested offsets.
• No relative-placement consistency violations were reported.
• Unconstrained flows were unaffected and produced identical results on the tested Titan circuits.

[vaughnbetz]

@amin1377 : is this one ready for review (assuming still WIP given the TBD in the description)?
Windows build looks like it has errors.
It would also be good to run a QoR run on the VTR designs or Titan designs to confirm no slowdown due to the new code when there are no relative placement macros.