issue module#

Design issues#

Experimental

This API is experimental and may change significantly without notice.

The physical-design issue list (“design checks”) reported by the runtime for a submitted design. Query it with design.issues() on a runtime design, which returns an IssueReport.

Issues form a class hierarchy, so a report can be filtered by any level of it, for example report.of(SignalIntegrityIssue). An issue of a type this version of JITX does not know is reported as its nearest known ancestor class, down to DesignIssue itself, and always carries its text, severity, the objects it references and any shapes.

class IssueCategory(*values)[source]#

Bases: IntEnum

The runtime’s issue categories. A report is partitioned by category; categories do not classify issues (use the issue classes for that).

SIGNAL_CONSTRAINT = 1#
TOPOLOGY = 2#
GEOMETRY = 3#
REALIZATION = 4#
ROUTING = 5#
LENGTH_TUNING = 6#
GENERAL = 7#
class Severity(*values)[source]#

Bases: IntEnum

Severity of an issue.

UNSPECIFIED = 0#
ERROR = 1#
WARNING = 2#
INFO = 3#
class CategoryStatus(*values)[source]#

Bases: IntEnum

Whether a category’s issues are final. PENDING means background tasks were still running when the report was taken, so the list may be incomplete.

UNKNOWN = 0#
PENDING = 1#
COMPLETE = 2#
class IssueObject(role, ref, instance)[source]#

Bases: object

A design object referenced by an issue.

Variables:

  • role (str) – What the object is to the issue, for example "pad", "pin", "route" or "route-segment".

  • ref (str) – Human-readable reference, possibly empty.

  • instance (object | None) – The Python object, or None if it could not be resolved, for example because the design was not submitted by this process.

Parameters:
role: str#
ref: str#
instance: object | None#
class IssueShape(role, shape, layers)[source]#

Bases: object

Geometry carried by an issue.

Variables:

  • role (str) – What the shape is to the issue, for example "overlap".

  • shape (Shape) – The shape, positioned in board coordinates.

  • layers (tuple[int, ...]) – Layer indices the shape applies to; empty if not layer-specific.

Parameters:
role: str#
shape: Shape#
layers: tuple[int, ...]#
class IssuePath(ref, pads, pins, route_segments)[source]#

Bases: object

A constrained path referenced by an issue.

Parameters:
ref: str#
pads: tuple[IssueObject, ...]#
pins: tuple[IssueObject, ...]#
route_segments: tuple[IssueObject, ...]#
class IssuePinPad(pads, pin)[source]#

Bases: object

A pin, and the pads realizing it.

Parameters:
pads: tuple[IssueObject, ...]#
pin: IssueObject#
class IssueStructure(path, source)[source]#

Bases: object

An active routing structure along a path.

Parameters:
path: IssuePath#
source: FileInfo | None#
class IssueIncidentStructure(proposed_path, structure)[source]#

Bases: object

A routing structure that could apply at a point, with the path it would apply to.

Parameters:
proposed_path: IssuePath#
structure: IssueStructure#
class IssueRoute(route, pads)[source]#

Bases: object

A route and its terminal pads.

Parameters:
route: IssueObject#
pads: tuple[IssueObject, ...]#
class DesignIssue[source]#

Bases: object

An issue reported by the runtime. Instances of this exact class are issues of a type this version of JITX does not recognize.

Variables:

  • text (str) – Human-readable description; always present.

  • severity (Severity | int) – The issue’s severity.

  • category (IssueCategory | int) – The category it was reported in, an IssueCategory or, for a category this version does not know, its number.

  • type (str) – The runtime’s name for the issue type, even when no class here matches it. For display only.

  • source (FileInfo | None) – Where in the design source the issue originates, if known.

  • objects (tuple[IssueObject, ...]) – Every design object the issue references.

  • shapes (tuple[IssueShape, ...]) – Every shape the issue carries.

  • group (IssueGroup) – The group the issue belongs to.

  • depth (int) – How many levels of the runtime’s hierarchy were understood.

  • details (Sequence[IssueDetail]) – The raw per-level detail sequence; details[depth:] is the part this version could not interpret.

text: str#
severity: Severity | int#
category: IssueCategory | int#
type: str#
source: FileInfo | None#
objects: tuple[IssueObject, ...]#
shapes: tuple[IssueShape, ...]#
group: IssueGroup#
depth: int#
details: Sequence[IssueDetail]#
property complete: bool#

True if every level of the runtime’s detail was understood.

class ConnectivityIssue[source]#

Bases: DesignIssue

A constrained path or requested route is not (correctly) connected.

class MissingRoute[source]#

Bases: ConnectivityIssue

A topology segment has no route.

Variables:
path_ref: str#
pads: tuple[IssueObject, ...]#
pins: tuple[IssueObject, ...]#
class DuplicateRoute[source]#

Bases: ConnectivityIssue

A topology segment has more than one route.

Variables:
path_ref: str#
pads: tuple[IssueObject, ...]#
pins: tuple[IssueObject, ...]#
route_segments: tuple[IssueObject, ...]#
class UnconnectedTopology[source]#

Bases: ConnectivityIssue

The ends of a topology segment are not connected.

Variables:
path_ref: str#
pads: tuple[IssueObject, ...]#
pins: tuple[IssueObject, ...]#
class UnassignedPin[source]#

Bases: ConnectivityIssue

A pin on a constrained path has no pin assignment.

Variables:

  • path_ref (str) – The constrained path, possibly empty.

  • pin (IssueObject) – The unassigned pin.

path_ref: str#
pin: IssueObject#
class BlockedPath[source]#

Bases: ConnectivityIssue

No path could be found for a requested route.

Variables:

route (IssueRoute | None) – The requested route and its terminal pads.

route: IssueRoute | None#
class DroppedRoute[source]#

Bases: ConnectivityIssue

A code route was dropped without being made.

Variables:

  • route (IssueRoute | None) – The dropped route and its terminal pads.

  • cause – Why it was dropped: "not-on-layer" (an end is not on the route’s layer), "not-in-topology" (the ends are on one net, but its declared topology does not join them directly), "different-nets", "never-connectable" (any other reason the ends can never be joined) or "conflicting" (other connections prevent it).

route: IssueRoute | None#
cause: str#
class UnmodelledVirtualConnection[source]#

Bases: ConnectivityIssue

A virtual connection joins the two ends of a topology segment, so no route is expected there, but it carries no pin model and the signal check cannot time the step.

Variables:
path_ref: str#
pads: tuple[IssueObject, ...]#
pins: tuple[IssueObject, ...]#
class SignalIntegrityIssue[source]#

Bases: DesignIssue

A signal constraint measurement. Measurements are reported for satisfied constraints too; check satisfied.

Variables:

  • measured_range (tuple[float, float] | None) – The measured (low, high) range.

  • acceptable_range (tuple[float, float] | None) – The constraint’s (low, high) range.

  • satisfied (bool) – Whether the measurement is within the acceptable range.

measured_range: tuple[float, float] | None#
acceptable_range: tuple[float, float] | None#
satisfied: bool#
class TimingIssue[source]#

Bases: SignalIntegrityIssue

A timing measurement; ranges are in seconds.

class UnmetTime[source]#

Bases: TimingIssue

A delay constraint measurement along one path.

Variables:

path (IssuePath | None) – The measured path.

path: IssuePath | None#
class UnmetTimeDiff[source]#

Bases: TimingIssue

A skew constraint measurement between two paths.

Variables:

  • longer_path (IssuePath | None) – The longer of the two paths.

  • shorter_path (IssuePath | None) – The shorter of the two paths.

longer_path: IssuePath | None#
shorter_path: IssuePath | None#
class LossIssue[source]#

Bases: SignalIntegrityIssue

A loss measurement; ranges are in dB.

class UnmetLoss[source]#

Bases: LossIssue

An insertion loss constraint measurement along one path.

Variables:

path (IssuePath | None) – The measured path.

path: IssuePath | None#
class RoutingStructureIssue[source]#

Bases: DesignIssue

A problem with the routing structures or structure models of a path.

class OverlappingStructure[source]#

Bases: RoutingStructureIssue

Routing structures overlap along a path.

Variables:
active: IssueStructure | None#
overlaps: tuple[IssueStructure, ...]#
class AmbiguousTouchingStructure[source]#

Bases: RoutingStructureIssue

Several routing structures meet at a point and it is ambiguous which applies.

Variables:
common_point: IssuePinPad | None#
alternatives: tuple[IssueIncidentStructure, ...]#
class MissingRoutingStructure[source]#

Bases: RoutingStructureIssue

A route segment on a constrained path has no routing structure.

Variables:
path_ref: str#
pads: tuple[IssueObject, ...]#
pins: tuple[IssueObject, ...]#
route_segments: tuple[IssueObject, ...]#
class MissingStructureModel[source]#

Bases: RoutingStructureIssue

A feature on a constrained path has no structure model; a placeholder model was used.

Variables:

  • path_ref (str) – The constrained path, possibly empty.

  • cause (str) – The runtime’s reason code, for example "NoDefForTraversedLayers".

  • error_point (IssuePinPad | None) – The feature without a model.

  • entry_layers (tuple[int, ...]) – Layers the path enters the feature on.

  • exit_layers (tuple[int, ...]) – Layers the path leaves the feature on.

  • via_def_name (str | None) – The configured via definition, if any.

path_ref: str#
cause: str#
error_point: IssuePinPad | None#
entry_layers: tuple[int, ...]#
exit_layers: tuple[int, ...]#
via_def_name: str | None#
class RealizationIssue[source]#

Bases: DesignIssue

A route could not be turned into final copper.

class UnrealizedRoute[source]#

Bases: RealizationIssue

A route could not be realized. Its geometry is in shapes.

Variables:

  • cause (str) – Why it could not be realized.

  • route_segments (tuple[IssueObject, ...]) – The affected route segments.

cause: str#
route_segments: tuple[IssueObject, ...]#
class UnsquiggledRoute[source]#

Bases: RealizationIssue

Length tuning could not generate a serpentine trace for a route.

Variables:

  • route (IssueRoute | None) – The route and its terminal pads.

  • cause (str) – Why, when known, e.g. a route end shaped to its pad; empty otherwise.

route: IssueRoute | None#
cause: str#
class GeometryIssue[source]#

Bases: DesignIssue

A problem with copper geometry.

class GeometricOverlap[source]#

Bases: GeometryIssue

Copper overlaps where it must not. The overlapping shapes and their layers are in shapes.

class TopologyIssue[source]#

Bases: DesignIssue

A problem in the topology definition. Subclasses carry the pins the problem is about; an instance of this exact class is described by text only.

class AmbiguousTopology[source]#

Bases: TopologyIssue

The signal path crosses a net whose connection points are joined in more than one way, so the path through them cannot be inferred.

Variables:
ends: tuple[IssueObject, ...]#
net_pins: tuple[IssueObject, ...]#
class UnroutedTopology[source]#

Bases: TopologyIssue

The signal path needs two points of a net that no route joins yet.

Variables:
ends: tuple[IssueObject, ...]#
gap: tuple[IssueObject, ...]#
class MissingPinModel[source]#

Bases: TopologyIssue

The signal path would pass through a part that has no pin model between the two pins named, so the signal cannot be followed through it.

Variables:
ends: tuple[IssueObject, ...]#
part: tuple[IssueObject, ...]#
class EquivalentPaths[source]#

Bases: TopologyIssue

Two paths of equal length run between the constraint’s ends. The constraint is checked over chosen; alternative is the other. Reported as a warning: the constraint still resolves.

Variables:
ends: tuple[IssueObject, ...]#
chosen: tuple[IssueObject, ...]#
alternative: tuple[IssueObject, ...]#
class GeneralIssue[source]#

Bases: DesignIssue

A general design-check message. Described by text only.

class IssueGroup(group_id, category, satisfied, text, issues=())[source]#

Bases: object

A group of related issues, for example every issue found checking one signal constraint.

Variables:

  • group_id (int) – The runtime’s identifier, stable for the same subject.

  • category (IssueCategory | int) – The category the group was reported in.

  • satisfied (bool) – True if the check behind the group passed.

  • text (str) – Human-readable summary; always present.

  • issues (tuple[DesignIssue, ...]) – The issues in the group.

Parameters:
group_id: int#
category: IssueCategory | int#
satisfied: bool#
text: str#
issues: tuple[DesignIssue, ...] = ()#
class CategoryEntry(category, status, groups)[source]#

Bases: object

The reported state of one category.

Parameters:
category: IssueCategory | int#
status: CategoryStatus | int#
groups: tuple[IssueGroup, ...]#
class IssueReport(generation, categories, _by_instance=dict())[source]#

Bases: object

The design issues of a design, as reported by the runtime.

Iterating yields every issue. The report is true if it contains any error-severity issue, so it can be used directly as a pass/fail check.

Variables:

  • generation (str) – Opaque token naming the runtime’s design generation the report was computed on.

  • categories (Mapping[IssueCategory | int, CategoryEntry]) – Every reported category, including empty ones.

Parameters:
generation: str#
categories: Mapping[IssueCategory | int, CategoryEntry]#
property errors: tuple[DesignIssue, ...]#

All error-severity issues.

property complete: bool#

True if every reported category is complete.

groups(category=None)[source]#

The groups of one category, or of all categories.

Parameters:

category (IssueCategory | int | None) – The category, or None for all.

Return type:

tuple[IssueGroup, ...]

of[T: DesignIssue](cls)[source]#

Issues that are instances of cls, including its subclasses.

>>> report.of(SignalIntegrityIssue)
Return type:

tuple[T, ...]

Parameters:

cls (type[T])

referencing(obj)[source]#

Issues that reference obj (by identity), for example a component or pad of the submitted design.

Return type:

tuple[DesignIssue, ...]

Parameters:

obj (object)

status(category)[source]#

Status of a category; UNKNOWN if it was not reported.

Return type:

CategoryStatus | int

Parameters:

category (IssueCategory | int)

text()[source]#

A human-readable rendering of the whole report.

Return type:

str

On this page