Test schematic version, add docs examples

Author: gpeairs

docs/src/routes.md

@@ -10,7 +10,7 @@ To draw a `Path` from a `Route`, you can use [`Path(r::Route, sty)`](@ref).
 
 More often, you won't work directly with the `Route` type but will instead use [`route!`](@ref) to extend an existing path to an endpoint according to the rules you specify.
 
-## Route API
+## Reference
 
 ```@docs
     Paths.Route
@@ -24,6 +24,8 @@ More often, you won't work directly with the `Route` type but will instead use [
     Paths.StraightAnd90
     Paths.StraightAnd45
     Paths.CompoundRouteRule
+    Paths.SingleChannelRouting
+    Paths.RouteChannel
 ```
 
 ### Route drawing
@@ -53,3 +55,128 @@ A `Route` supports endpoint inspection much like a `Path` does:
     Paths.p1(::Paths.Route)
     Paths.α1(::Paths.Route)
 ```
+
+## Examples
+
+### Channel routing
+
+`RouteChannels` offer a way to run routes in parallel, with routes joining or leaving a channel at different points. Using `SingleChannelRouting`, we can set the "track" (a path offset from the channel centerline) for each route through the channel, as well as some rules for joining and leaving the channel from route start and end points. Here's a basic example with a straight channel:
+
+```@example 1
+using DeviceLayout, .PreferredUnits, FileIO
+import DeviceLayout.Graphics: inch
+# Define start and end points for various routes
+p0s = [
+    Point(100.0, -200.0)μm,  # Enter and exit from bottom
+    Point(600.0, -150)μm,    # Enter from bottom, exit from right
+    Point(-100.0, -100.0)μm, # Enter from lower left, exit from right
+    Point(50.0, 150)μm,      # Enter from top, exit from right
+    Point(100.0, 200.0)μm    # Enter and exit from top
+]
+
+p1s = [
+    Point(400.0, -200.0)μm,
+    Point(1100.0, -150.0)μm,
+    Point(1200.0, 50.0)μm,
+    Point(1100.0, 150.0)μm,
+    Point(900.0, 200.0)μm
+]
+
+# Create channel
+channel_path = Path()
+straight!(channel_path, 1mm, Paths.Trace(0.1mm))
+channel = Paths.RouteChannel(channel_path)
+# Initialize paths
+paths = [Path(p) for p in p0s]
+# Define route rule 
+transition_rule = Paths.StraightAnd90(25μm) # Manhattan with 25μm bend radius
+margin = 50.0μm # Room for bends between endpoints and channel
+rule = Paths.SingleChannelRouting(channel, transition_rule, margin)
+# Set tracks
+tracks = [1, 1, 2, 3, 4] # First two share a track
+setindex!.(Ref(rule.segment_tracks), tracks, paths)
+# Draw routes
+for (pa, p1) in zip(paths, p1s)
+    route!(pa, p1, 0.0°, rule, Paths.Trace(2μm))
+end
+c = Cell("test")
+render!.(c, paths, GDSMeta())
+render!(c, channel_path, GDSMeta(2))
+save("straight_channel.svg", flatten(c); width=6inch, height=2inch)
+```
+
+```@raw html
+<img src="../straight_channel.svg" style="width:6in;"/>
+```
+
+We can also have curved channels, like the `BSpline`-based example below. For the transition rule, `StraightAnd90` would no longer work for the paths that join the channel at an angle, so we use `BSplineRouting` instead. We also enable `auto_speed` and `auto_curvature` on that rule to help smooth out the B-splines and maintain continuous curvature.
+
+```@example 1
+# Create BSpline channel
+channel_path = Path()
+bspline!(
+    channel_path,
+    [Point(0.5, 0.5)mm, Point(1.0mm, 0.0μm)],
+    0°,
+    Paths.Trace(0.1mm),
+    auto_speed=true,
+    auto_curvature=true
+)
+channel = Paths.RouteChannel(channel_path)
+# Initialize paths
+paths = [Path(p) for p in p0s]
+# Define route rule 
+transition_rule = Paths.BSplineRouting(auto_speed=true, auto_curvature=true)
+margin = 50.0μm
+rule = Paths.SingleChannelRouting(channel, transition_rule, margin)
+# Set tracks
+tracks = [1, 1, 2, 3, 4] # First two share a track
+setindex!.(Ref(rule.segment_tracks), tracks, paths)
+# Draw routes
+for (pa, p1) in zip(paths, p1s)
+    route!(pa, p1, 0.0°, rule, Paths.Trace(2μm))
+end
+c = Cell("test")
+render!.(c, paths, GDSMeta())
+render!(c, channel_path, GDSMeta(2))
+save("bspline_channel.svg", flatten(c); width=6inch, height=4inch)
+```
+
+```@raw html
+<img src="../bspline_channel.svg" style="width:6in;"/>
+```
+
+Channels can also have variable width, like the example below using the `TaperTrace` style on a compound segment consisting of four turns.
+
+```@example 1
+# Create tapered, composite channel
+channel_path = Path()
+turn!(channel_path, 90°, 0.25mm, Paths.Trace(0.1mm))
+turn!(channel_path, -90°, 0.25mm)
+turn!(channel_path, -90°, 0.25mm)
+turn!(channel_path, 90°, 0.25mm)
+simplify!(channel_path)
+setstyle!(channel_path[1], Paths.TaperTrace(0.1mm, 0.05mm))
+channel = Paths.RouteChannel(channel_path)
+# Initialize paths
+paths = [Path(p) for p in p0s]
+# Define route rule 
+transition_rule = Paths.BSplineRouting(auto_speed=true, auto_curvature=true)
+margin = 50.0μm
+rule = Paths.SingleChannelRouting(channel, transition_rule, margin)
+# Set tracks
+tracks = [1, 1, 2, 3, 4] # First two share a track
+setindex!.(Ref(rule.segment_tracks), tracks, paths)
+# Draw routes
+for (pa, p1) in zip(paths, p1s)
+    route!(pa, p1, 0.0°, rule, Paths.Trace(2μm))
+end
+c = Cell("test")
+render!.(c, paths, GDSMeta())
+render!(c, channel_path, GDSMeta(2))
+save("compound_channel.svg", flatten(c); width=6inch, height=4inch)
+```
+
+```@raw html
+<img src="../compound_channel.svg" style="width:6in;"/>
+```

src/paths/channels.jl

@@ -1,16 +1,26 @@
 """
     RouteChannel{T} <: AbstractComponent{T}
     RouteChannel(pa::Path)
+
+A channel that routes can be guided through along parallel tracks.
+
+Used in `route!` with [`Paths.SingleChannelRouting`](@ref).
+
+The `Path` used to construct a `RouteChannel` should use `Trace` styles only.
+
+A `RouteChannel` is an `AbstractComponent` with the same hooks as its `Path` and
+an empty geometry.
 """
 struct RouteChannel{T} <: AbstractComponent{T}
     path::Path{T}
     node::Node{T} # path as single node
-    capacity::Int # Currently unused
 end
+name(ch::RouteChannel) = name(ch.path)
+DeviceLayout.hooks(ch::RouteChannel) = DeviceLayout.hooks(ch.path)
 
-function RouteChannel(pa::Path{T}, capacity=0) where {T}
-    length(nodes(pa)) != 1 && return RouteChannel{T}(pa, simplify(pa), capacity)
-    return RouteChannel{T}(pa, only(nodes(pa)), capacity)
+function RouteChannel(pa::Path{T}) where {T}
+    length(nodes(pa)) != 1 && return RouteChannel{T}(pa, simplify(pa))
+    return RouteChannel{T}(pa, only(nodes(pa)))
 end
 
 # Return a node corresponding to the section of the channel that the segment actually runs through
@@ -24,14 +34,14 @@ function segment_channel_section(
 ) where {T}
     d = wireseg_stop - wireseg_start
     # Adjust for margins and track vs channel direction to get the channel node section used by actual segment
-    if abs(d) <= 2 * margin + prev_width + next_width
+    if abs(d) <= 2 * margin + prev_width / 2 + next_width / 2
         # handle case where margin consumes entire segment
         # Just have a zero length Straight at the midpoint
         track_mid = (wireseg_start + wireseg_stop) / 2
         midpoint = ch.node.seg(track_mid)
         middir = direction(ch.node.seg, track_mid)
         channel_section = Node(
-            Straight(zero(T), midpoint, middir),
+            Straight(zero(T); p0=midpoint, α0=middir),
             SimpleTrace(width(ch.node.sty, track_mid))
         )
     elseif d > zero(d) # segment is along channel direction
@@ -56,13 +66,15 @@ function segment_channel_section(
     return channel_section
 end
 
+# Actual routed path segment along a track offset from the channel path
 function track_path_segment(n_tracks, channel_section, track_idx; reversed=false)
     return offset(
         channel_section.seg,
         track_section_offset(n_tracks, width(channel_section.sty), track_idx; reversed)
     )
 end
 
+# Offset coordinate or function for the section of track with given width
 function track_section_offset(
     n_tracks,
     section_width::Coordinate,
@@ -192,33 +204,97 @@ function _reconcile_curvature!(n::Node{T}, rule::BSplineRouting) where {T}
     end
 end
 
-struct SingleChannelRouting{T} <: AbstractChannelRouting
+"""
+    struct SingleChannelRouting{T <: Coordinate} <: AbstractChannelRouting
+    SingleChannelRouting(ch::RouteChannel, transition_rule::RouteRule, margin::T)
+    SingleChannelRouting(ch::RouteChannel, transition_rules, margins)
+
+A `RouteRule` for guiding routed paths along tracks in a [`Paths.RouteChannel`](@ref).
+
+## Tracks
+
+"Tracks" are offsets of the channel's path, with equal spacing between each other
+and the extents of the channel's trace width. Tracks are ordered from right to left
+when looking along the channel. For example, track 1 is the bottom track
+(most negative offset) for a channel directed along the positive x axis, while
+the highest track index is the top track.
+
+The user manually assigns tracks to paths that will be routed with
+`rule::SingleChannelRouting` using `set_track!(rule, path)` for each path,
+prior to calling `route!(path, ...)`.
+
+If used for schematic routing, the track is supplied as a keyword argument,
+defaulting to a new track added at the top of the channel:
+`route!(g::SchematicGraph, rule, ...; track=num_tracks(rule)+1)`.
+
+## Routing
+
+A path routed from `p0` to `p1` using this rule will enter the channel
+at the channel's closest point to `p0` and exit at the closest point to `p1` if
+`margin` is zero. For nonzero `margin`, the entry and exit points are each shifted
+towards the other along the channel by `margin`, allowing more space for the
+transitions into and out of the channel.
+
+The middle "tracked" section is offset from the channel's center line according to
+the path's track, the maximum track assigned to any path by the rule,
+and the channel width.
+
+The path is routed from `p0` to the tracked section and from the tracked section
+to `p1` using `transition_rule`.
+
+Transition rules and margins can also be supplied as tuples to the constructor
+to allow different parameters for entry and exit transitions.
+"""
+mutable struct SingleChannelRouting{T <: Coordinate} <: AbstractChannelRouting
     channel::RouteChannel{T}
     transition_rules::Tuple{<:RouteRule, <:RouteRule}
     transition_margins::Tuple{T, T}
-    segment_tracks::Dict{Path{T}, Int}
+    segment_tracks::Dict{Path, Int}
+    global_channel::RouteChannel{T}
+    function SingleChannelRouting(
+        ch::RouteChannel{T},
+        rules,
+        margins,
+        tracks=Dict{Path, Int}()
+    ) where {T}
+        return new{T}(ch, rules, margins, tracks)
+    end
+end
+function SingleChannelRouting(
+    ch::RouteChannel{T},
+    rule::RouteRule,
+    margin,
+    tracks...
+) where {T}
+    return SingleChannelRouting(ch, (rule, rule), (margin, margin), tracks...)
 end
-function SingleChannelRouting(ch::RouteChannel{T}, rule::RouteRule, margin::T) where {T}
-    return SingleChannelRouting{T}(ch, (rule, rule), (margin, margin), Dict{Path{T}, Int}())
+function channel(rule::SingleChannelRouting)
+    isdefined(rule, :global_channel) && return rule.global_channel
+    return rule.channel
 end
 entry_rules(scr::SingleChannelRouting) = [first(scr.transition_rules)]
 exit_rule(scr::SingleChannelRouting) = last(scr.transition_rules)
 entry_margin(scr::SingleChannelRouting) = first(scr.transition_margins)
 exit_margin(scr::SingleChannelRouting) = last(scr.transition_margins)
-num_tracks(scr::SingleChannelRouting) = maximum(values(scr.segment_tracks))
-track_idx(scr, pa) = scr.segment_tracks[pa]
+function num_tracks(scr::SingleChannelRouting)
+    isempty(scr.segment_tracks) && return 0
+    return maximum(values(scr.segment_tracks))
+end
+function track_idx(scr, pa)
+    return scr.segment_tracks[pa]
+end
 function set_track!(scr, pa, track_idx)
     return scr.segment_tracks[pa] = track_idx
 end
 
 function track_path_segments(rule::SingleChannelRouting, pa::Path, endpt)
-    wireseg_start = pathlength_nearest(rule.channel.node.seg, p1(pa))
-    wireseg_stop = pathlength_nearest(rule.channel.node.seg, endpt)
+    wireseg_start = pathlength_nearest(channel(rule).node.seg, p1(pa))
+    wireseg_stop = pathlength_nearest(channel(rule).node.seg, endpt)
     return [
         track_path_segment(
             num_tracks(rule),
             segment_channel_section(
-                rule.channel,
+                channel(rule),
                 wireseg_start,
                 wireseg_stop,
                 2 * entry_margin(rule),
@@ -229,13 +305,3 @@ function track_path_segments(rule::SingleChannelRouting, pa::Path, endpt)
         )
     ]
 end
-
-function _update_with_graph!(
-    rule::SingleChannelRouting,
-    route_node,
-    graph;
-    track=num_tracks(rule) + 1,
-    kwargs...
-)
-    return set_track!(rule, route_node.component._path, track)
-end

src/paths/paths.jl

@@ -1319,7 +1319,7 @@ function split(seg::Segment, sty::Style, x)
 end
 
 function split(seg::ContinuousSegment, x)
-    if !(zero(x) < x < pathlength(seg))
+    if !(zero(x) <= x <= pathlength(seg))
         throw(ArgumentError("x must be between 0 and pathlength(seg)"))
     end
     return _split(seg, x)

src/paths/routes.jl

@@ -33,6 +33,7 @@ abstract type RouteRule end
         min_bend_radius = 200μm
         max_bend_radius = Inf*μm
     end
+    StraightAnd90(r) = StraightAnd90(min_bend_radius=r, max_bend_radius=r)
 
 Specifies rules for routing from one point to another using straight segments and 90° bends.
 
@@ -46,12 +47,14 @@ Base.@kwdef struct StraightAnd90 <: RouteRule
     min_bend_radius = 200μm
     max_bend_radius = Inf * μm
 end
+StraightAnd90(r) = StraightAnd90(min_bend_radius=r, max_bend_radius=r)
 
 """
     Base.@kwdef struct StraightAnd45 <: RouteRule
         min_bend_radius = 200μm
         max_bend_radius = Inf*μm
     end
+    StraightAnd45(r) = StraightAnd45(min_bend_radius=r, max_bend_radius=r)
 
 Specifies rules for routing from one point to another using using straight segments and 45° bends.
 
@@ -65,6 +68,7 @@ Base.@kwdef struct StraightAnd45 <: RouteRule
     min_bend_radius = 200μm
     max_bend_radius = Inf * μm
 end
+StraightAnd45(r) = StraightAnd45(min_bend_radius=r, max_bend_radius=r)
 
 """
     Base.@kwdef struct BSplineRouting <: RouteRule
@@ -610,6 +614,3 @@ function _route_leg!(
     turn!(p, 45° * sign(perp), bend_r, seg_sty[2])
     return d_diag > zero(dx) && straight!(p, d_diag, seg_sty[3])
 end
-
-function _update_with_plan!(rule::RouteRule, route_node, schematic) end
-function _update_with_graph!(rule::RouteRule, route_node, graph; kwargs...) end

src/paths/segments/offset.jl

@@ -31,6 +31,16 @@ struct GeneralOffset{T, S} <: OffsetSegment{T, S}
     offset
 end
 
+convert(::Type{ConstantOffset{T}}, x::ConstantOffset) where {T} =
+    ConstantOffset(convert(Segment{T}, x.seg), convert(T, x.offset))
+convert(::Type{ConstantOffset{T}}, x::ConstantOffset{T}) where {T} = x
+convert(::Type{Segment{T}}, x::ConstantOffset) where {T} = convert(ConstantOffset{T}, x)
+
+convert(::Type{GeneralOffset{T}}, x::GeneralOffset) where {T} =
+    OffsetSegment(convert(Segment{T}, x.seg), x.offset)
+convert(::Type{GeneralOffset{T}}, x::GeneralOffset{T}) where {T} = x
+convert(::Type{Segment{T}}, x::GeneralOffset) where {T} = convert(GeneralOffset{T}, x)
+
 copy(s::OffsetSegment) = OffsetSegment(copy(s.seg), s.offset)
 getoffset(s::ConstantOffset, l...) = s.offset
 getoffset(s::GeneralOffset{T}) where {T} = l -> uconvert(unit(T), s.offset(l))