layout module#

The physical design (layout) of a design held by the runtime.

Reached through RuntimeDesign.layout. Requests change the design in the runtime, as if made in the UI. Placements are applied to the local design tree from the reply; routes, vias, control points, and area regions appear in it when the runtime reports them. monitor registers callbacks on changes (see jitx.run.monitor), and emit sends user events.

exception RequestRejected(kind, message, operation=None)[source]#

Bases: RuntimeError

The runtime refused a request.

Parameters:

  • kind (str) – The runtime’s error kind.

  • message (str) – The runtime’s reason.

  • operation (int | None) – For a batch, the index of the operation the runtime refused, counted in the order the batch sent them; None if the refusal is not about one operation.

class RouteSetting(*values)[source]#

Bases: StrEnum

A route setting, as named by the reset argument of a modification.

>>> rd.layout.modify(route, reset=[RouteSetting.Width])
Width = 'width'#

The trace width.

Space = 'space'#

The trace clearance.

PairSpace = 'pair_space'#

The differential pair spacing.

EnvelopeOverhead = 'envelope_overhead'#

The extra width of the length matching region.

class PendingPlacement(target)[source]#

Bases: object

The resulting placement of a component placed in a batch, available once the batch has been sent.

Parameters:

target (Component)

property done: bool#

Whether the batch was sent and the placement is available.

property placement: Placement#

The board-absolute placement the runtime reported.

Raises:

RuntimeError – if the batch has not been sent.

class PendingSync[source]#

Bases: _Pending

The outcome of a sync in a batch, available once the batch has been sent.

property done: bool#

Whether the batch was sent and the outcome is available.

property settled: bool#

Whether background tasks had finished; False if the sync timed out.

Raises:

RuntimeError – if the batch has not been sent.

class PendingRoute(rmap)[source]#

Bases: _Pending

A route created by a request. Its runtime id is available once the batch has been sent; the Route object once the runtime reports it routed or blocked (follow the request with a sync to wait for that), or after a capture.

Parameters:

rmap (Callable[[], ReverseMapper])

property done: bool#

Whether the batch was sent and the route id is available.

property key: CompositeKey#

The runtime id of the route.

Raises:

RuntimeError – if the batch has not been sent.

property route: Route | None#

The route in the current design tree, or None if the runtime has not reported it yet. Its status tells whether it is routed or blocked.

class PendingVia(rmap, key=None)[source]#

Bases: _Pending

A via created or updated by a request. Its runtime id and position are available once the batch has been sent; the Via object once the runtime reports it (follow the request with a sync to wait for that), or after a capture.

Parameters:

  • rmap (Callable[[], ReverseMapper])

  • key (CompositeKey | None)

property done: bool#

Whether the batch was sent and the via id and position are available.

property key: CompositeKey#

The runtime id of the via.

Raises:

RuntimeError – if the batch has not been sent.

property position: Point#

The board-absolute position of the via, after the runtime moved it to a free spot, if it did.

Raises:

RuntimeError – if the batch has not been sent.

property route: PendingRoute | None#

The route from the via’s origin to the via; None if they coincide or the via was updated rather than created.

property via: Via | None#

The via in the current design tree, or None if the runtime has not reported it yet.

class PendingControlPoint(rmap, key=None)[source]#

Bases: _Pending

A control point created or updated by a request. Its runtime id, and the routes made to it, are available once the batch has been sent; the control point object once the runtime reports it (follow the request with a sync to wait for that), or after a capture.

Parameters:

  • rmap (Callable[[], ReverseMapper])

  • key (CompositeKey | None)

property done: bool#

Whether the batch was sent and the id is available.

property key: CompositeKey#

The runtime id of the control point.

Raises:

RuntimeError – if the batch has not been sent.

property routes: Sequence[PendingRoute]#

The routes made from the origin(s) to the control point when it was created; empty for an update.

property placement: Placement | None#

For an update, the resulting board-absolute placement.

property control_point: ControlPoint | None#

The control point in the current design tree, or None if the runtime has not reported it yet.

class PendingRegion(rmap)[source]#

Bases: _Pending

An area region created by a request. Its runtime id is available once the batch has been sent; the model object (the region’s feature, or for a copper pour its Pour) once the runtime reports it (follow the request with a sync to wait for that), or after a capture.

Parameters:

rmap (Callable[[], ReverseMapper])

property done: bool#

Whether the batch was sent and the region id is available.

property key: CompositeKey#

The runtime id of the region.

Raises:

RuntimeError – if the batch has not been sent.

property region: Feature | Pour | None#

The region in the current design tree, or None if the runtime has not reported it yet. A convex hull region’s feature has a ConvexHull shape holding its anchors and the evaluated polygon; a copper pour’s shape is its poured copper.

type RegionFeature = KeepOut | Soldermask | Silkscreen | Paste | Glue | Finish | Custom | Cutout | Pour#

What an area region can be: a keepout, a cutout, a surface feature, or a single-layer copper pour.

type RegionElement = Pad | Port | Via | PendingVia | ControlPoint | PendingControlPoint | Component | object#

A board element a region refers to (an origin, a hull anchor).

type RouteEndpoint = Port | Pad | Via | PendingVia | PendingControlPoint | object#

What a route can start or end at: a pad, a port mapped to a single pad, a via (or a PendingVia from an earlier request), or a control point (or a PendingControlPoint) or one of its endpoints.

type DiffPairPads = DiffPair | tuple[Port | Pad | Via | PendingVia, Port | Pad | Via | PendingVia]#

The two sides of a differential pair: a DiffPair port whose p and n each map to a single pad, or (p, n) as pads, vias, or ports mapped to a single pad.

type Deletable = Route | Via | ControlPoint | Feature | Pour | PendingRoute | PendingVia | PendingControlPoint | PendingRegion#

What delete() accepts.

class AsyncBatch(rmap, send)[source]#

Bases: _Batch

Requests sent together as one request when the async with block exits without an exception.

The runtime applies the batch in order and all-or-nothing, as one undoable step. Placing a component again in the same batch applies to its earlier placement in the batch.

>>> async with design.layout.batch() as b:
...     p = b.place(design.root.u1, (10, 5), 90)
...     b.place(design.root.u2, on=Side.Bottom)
>>> p.placement
Raises:

RequestRejected – from the block exit, if the runtime refused the batch.

Parameters:

  • rmap (Callable[[], ReverseMapper])

  • send (Callable[[pdpb2.PhysicalDesignOperations], Awaitable[pdpb2.PhysicalDesignOperationsResponse]])

class SyncBatch(rmap, send)[source]#

Bases: _Batch

Requests sent together as one request when the with block exits without an exception.

The runtime applies the batch in order and all-or-nothing, as one undoable step. Placing a component again in the same batch applies to its earlier placement in the batch.

>>> with design.layout.batch() as b:
...     p = b.place(design.root.u1, (10, 5), 90)
...     b.place(design.root.u2, on=Side.Bottom)
>>> p.placement
Raises:

RequestRejected – from the block exit, if the runtime refused the batch.

Parameters:

  • rmap (Callable[[], ReverseMapper])

  • send (Callable[[pdpb2.PhysicalDesignOperations], pdpb2.PhysicalDesignOperationsResponse])

class AsyncLayout(rmap, send, *, monitor=None, publish=None)[source]#

Bases: object

The layout of an async runtime design. Each request method is one request; see batch() to send several as one.

Parameters:

  • rmap (Callable[[], ReverseMapper])

  • send (Callable[[pdpb2.PhysicalDesignOperations], Awaitable[pdpb2.PhysicalDesignOperationsResponse]])

  • monitor (LayoutMonitor | None)

  • publish (Callable[[pdpb2.PhysicalDesignEvent], Awaitable[None]] | None)

property monitor: LayoutMonitor#

Callbacks on changes to the layout. See LayoutMonitor.

async emit(event)[source]#

Send a user event to the other clients monitoring this design.

Raises:

  • TypeError – if the event’s data is not JSON-compatible.

  • ValueError – if an object has no runtime ID.

Return type:

None

Parameters:

event (UserEvent)

batch()[source]#

Start a batch of requests, sent as one request. See AsyncBatch.

Return type:

AsyncBatch

async sync(timeout=None)[source]#

Wait until the runtime has no background tasks running (routing, checks, …), so the design is settled.

Parameters:

timeout (float | None) – Seconds to wait at most; None for the runtime’s default.

Return type:

bool

Returns:

True if everything settled, False if the wait timed out.

async place(target, /, position=None, rotation=None, *, on=None)[source]#

Place a component on the board, as if dragged in the UI.

Overloads:
Parameters:

  • target (Component) – The component to place.

  • position (Placement | Point | None) – A board-absolute Placement, setting position, rotation, and side together, or the board-absolute position. Omitted aspects keep their current value in the runtime.

  • rotation (float | None) – Rotation in degrees.

  • on (Side | None) – The board side.

Returns:

The resulting board-absolute placement.

Raises:

RequestRejected – if the runtime refused the request.

Return type:

Placement

async route(start, end, layer, *, turns=None, width=None, space=None, pair_space=None, envelope_overhead=None, pour=None, wait=True)[source]#

Route between two endpoints. See AsyncBatch.route().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingRoute

async via(definition, origin, position, layer, *, turns=None, force=False, width=None, space=None, wait=True)[source]#

Place a routing via. See AsyncBatch.via().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingVia

async update_via(via, *, position=None, definition=None, force=False, wait=True)[source]#

Move a via or change its definition. See AsyncBatch.update_via().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingVia

async modify(route, *, turns=None, width=None, space=None, pair_space=None, envelope_overhead=None, pour=None, reset=(), wait=True)[source]#

Change a route’s sketch or settings. See AsyncBatch.modify().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

None

async route_point(origin, position, layer, *, radius=None, size=None, turns=None, width=None, space=None, wait=True)[source]#

Add a route point. See AsyncBatch.route_point().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

async pair_insertion(pair, position, rotation, layer, *, invert=False, width=None, space=None, pair_space=None, wait=True)[source]#

Add a differential pair insertion point. See AsyncBatch.pair_insertion().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

async pair_point(origin, position, rotation, layer, *, turns=None, width=None, space=None, pair_space=None, wait=True)[source]#

Add a pair point. See AsyncBatch.pair_point().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

async drop_pair_insertion(pair, layer, *, pull=None, width=None, space=None, pair_space=None, wait=True)[source]#

Add a pair insertion point placed next to its pads. See AsyncBatch.drop_pair_insertion().

Parameters:

  • wait (bool) – Wait for background work (routing to the point) to finish.

  • pair (DiffPairPads)

  • layer (int)

  • pull (bool | None)

  • width (float | None)

  • space (float | None)

  • pair_space (float | None)

Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

async update_control(control, *, position=None, rotation=None, invert=False, radius=None, size=None, wait=True)[source]#

Move, reshape, or invert a control point. See AsyncBatch.update_control().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

async region(feature, /, *, origin=None, net=None, wait=True)[source]#

Add an area region. See AsyncBatch.region().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingRegion

async update_region(region, /, *, shape=None, layers=None, side=None, rank=None, pour=None, via=None, route=None, name=None, origin=None, net=None, wait=True)[source]#

Change an area region. See AsyncBatch.update_region().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

None

async delete(*objects)[source]#

Delete routes, vias, control points, and area regions. See AsyncBatch.delete().

Raises:

RequestRejected – if the runtime refused the request.

Return type:

None

Parameters:

objects (Deletable)

class SyncLayout(rmap, send, *, monitor=None, publish=None)[source]#

Bases: object

The layout of a sync runtime design. Each request method is one request; see batch() to send several as one.

Parameters:

  • rmap (Callable[[], ReverseMapper])

  • send (Callable[[pdpb2.PhysicalDesignOperations], pdpb2.PhysicalDesignOperationsResponse])

  • monitor (LayoutMonitor | None)

  • publish (Callable[[pdpb2.PhysicalDesignEvent], None] | None)

property monitor: LayoutMonitor#

Callbacks on changes to the layout. See LayoutMonitor.

emit(event)[source]#

Send a user event to the other clients monitoring this design.

Raises:

  • TypeError – if the event’s data is not JSON-compatible.

  • ValueError – if an object has no runtime ID.

Return type:

None

Parameters:

event (UserEvent)

batch()[source]#

Start a batch of requests, sent as one request. See SyncBatch.

Return type:

SyncBatch

sync(timeout=None)[source]#

Wait until the runtime has no background tasks running (routing, checks, …), so the design is settled.

Parameters:

timeout (float | None) – Seconds to wait at most; None for the runtime’s default.

Return type:

bool

Returns:

True if everything settled, False if the wait timed out.

place(target, /, position=None, rotation=None, *, on=None)[source]#

Place a component on the board, as if dragged in the UI.

Overloads:
Parameters:

  • target (Component) – The component to place.

  • position (Placement | Point | None) – A board-absolute Placement, setting position, rotation, and side together, or the board-absolute position. Omitted aspects keep their current value in the runtime.

  • rotation (float | None) – Rotation in degrees.

  • on (Side | None) – The board side.

Returns:

The resulting board-absolute placement.

Raises:

RequestRejected – if the runtime refused the request.

Return type:

Placement

route(start, end, layer, *, turns=None, width=None, space=None, pair_space=None, envelope_overhead=None, pour=None, wait=True)[source]#

Route between two endpoints. See SyncBatch.route().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingRoute

via(definition, origin, position, layer, *, turns=None, force=False, width=None, space=None, wait=True)[source]#

Place a routing via. See SyncBatch.via().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingVia

update_via(via, *, position=None, definition=None, force=False, wait=True)[source]#

Move a via or change its definition. See SyncBatch.update_via().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingVia

modify(route, *, turns=None, width=None, space=None, pair_space=None, envelope_overhead=None, pour=None, reset=(), wait=True)[source]#

Change a route’s sketch or settings. See SyncBatch.modify().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

None

route_point(origin, position, layer, *, radius=None, size=None, turns=None, width=None, space=None, wait=True)[source]#

Add a route point. See SyncBatch.route_point().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

pair_insertion(pair, position, rotation, layer, *, invert=False, width=None, space=None, pair_space=None, wait=True)[source]#

Add a differential pair insertion point. See SyncBatch.pair_insertion().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

pair_point(origin, position, rotation, layer, *, turns=None, width=None, space=None, pair_space=None, wait=True)[source]#

Add a pair point. See SyncBatch.pair_point().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

drop_pair_insertion(pair, layer, *, pull=None, width=None, space=None, pair_space=None, wait=True)[source]#

Add a pair insertion point placed next to its pads. See SyncBatch.drop_pair_insertion().

Parameters:

  • wait (bool) – Wait for background work (routing to the point) to finish.

  • pair (DiffPairPads)

  • layer (int)

  • pull (bool | None)

  • width (float | None)

  • space (float | None)

  • pair_space (float | None)

Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

update_control(control, *, position=None, rotation=None, invert=False, radius=None, size=None, wait=True)[source]#

Move, reshape, or invert a control point. See SyncBatch.update_control().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingControlPoint

region(feature, /, *, origin=None, net=None, wait=True)[source]#

Add an area region. See SyncBatch.region().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

PendingRegion

update_region(region, /, *, shape=None, layers=None, side=None, rank=None, pour=None, via=None, route=None, name=None, origin=None, net=None, wait=True)[source]#

Change an area region. See SyncBatch.update_region().

Parameters:
Raises:

RequestRejected – if the runtime refused the request.

Return type:

None

delete(*objects)[source]#

Delete routes, vias, control points, and area regions. See SyncBatch.delete().

Raises:

RequestRejected – if the runtime refused the request.

Return type:

None

Parameters:

objects (Deletable)