advice.hpp File Reference

The advice file (design doc 17, issue #26): typed hints for the router, written by a person, a script or a language model, and read by the engine like any other input. More...

#include <cstdint>
#include <map>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include <nlohmann/json.hpp>
#include "geom/point.hpp"
#include "model/board.hpp"
#include "model/rules.hpp"
#include "route/router.hpp"

Go to the source code of this file.

Classes
struct	tmk::advice::Region
struct	tmk::advice::Advice
struct	tmk::advice::Applied
	What the router is given for an advice file, and what each hint became (for the log, the summary and the viewer). More...
struct	tmk::advice::AliasMap
	Aliases for net names and part references (a redacted stuck report): the advice an advisor writes uses the aliases, and unalias puts the board's names back before the references are checked. More...

Namespaces
namespace	tmk
namespace	tmk::advice

Functions
Advice	tmk::advice::parse_advice (std::string_view json_text, const std::string &source="advice")
	Parses and validates the text of an advice file. Throws std::runtime_error naming source and the entry ("regions[1].rect").
Advice	tmk::advice::load_advice_file (const std::string &path)
	Reads a file (size-limited); throws on a missing file or a syntax or content error.
void	tmk::advice::check_advice_refs (const Advice &a, const model::Board &b, std::vector< std::string > *warnings=nullptr)
	Checks every name against the board: nets, pads (REF.NUM, on one net), copper layers.
Applied	tmk::advice::apply_advice (const Advice &a, const model::Board &b)
	check_advice_refs, then the RouterOptions::AdviceSet: layer masks and costs, and for each region a rule area plus disallow rules (doc 05 §34) that name its nets.
nlohmann::json	tmk::advice::advice_to_json (const Advice &a)
	The advice as JSON, with the board's real names: what is saved beside the output so that --advice FILE repeats a run.
nlohmann::json	tmk::advice::advice_schema ()
	The hint types an advisor may use, as JSON (goes into the stuck report so an advisor adapts to the engine it talks to).
void	tmk::advice::unalias (Advice &a, const AliasMap &m)

Variables
constexpr std::size_t	tmk::advice::kMaxFirstNets = 64
	Upper bounds on what one file may ask for (an advisor is not trusted to be sensible, doc 17 §6).
constexpr std::size_t	tmk::advice::kMaxPriority = 512
constexpr std::size_t	tmk::advice::kMaxRegions = 24
constexpr std::size_t	tmk::advice::kMaxPolygon = 64
constexpr std::size_t	tmk::advice::kMaxRegionNets = 64
constexpr std::size_t	tmk::advice::kMaxNote = 2000
constexpr int	tmk::advice::kMaxVariants = 8
constexpr int	tmk::advice::kDefaultVariants = 4

Detailed Description

The advice file (design doc 17, issue #26): typed hints for the router, written by a person, a script or a language model, and read by the engine like any other input.

The engine never talks to a model; a model is one possible writer of this file.

{ "version": 1, "note": "free text, logged and never acted on", "variants": 4, // advised variants added to the portfolio (default 4) "first_nets": ["USB_DP", "USB_DM"], // routed first; other nets do not rip them "priority": [["U1.A1", "J2.3"]], // connections (pad to pad, either order) routed first "layers": {"no_tracks": ["In2.Cu"], // no new tracks on these copper layers (vias still pass) "cost": {"F.Cu": 1.5}}, // track cost factor per layer (1 to 1000) "regions": [{"name": "north channel", // a region of the board (millimetres, the board file's axes) "rect": [10, 10, 20, 14], // or "polygon": [[x, y], ...] "layers": ["F.Cu"], // default: every copper layer "reserve_for": ["NET1", "NET2"], // only these nets may put copper there ... "avoid_nets": ["NET3"], // ... or: these nets may not (exactly one of the two) "tracks": true, "vias": true}] // which copper is kept out (both by default) }

Advice never contains copper and never changes a rule's value: it changes the order of the connections, the cost of a layer, and where some nets may not go, all inside the router's search. Every route is still judged by the exact check, and the advised attempts run as extra portfolio variants next to the unadvised ones, so the winner can only be better.

Reading is strict, as for the rule overrides (doc 15 §6.3): an unknown key, a wrong type or a value out of range is an error naming the file and the entry, never ignored (a typo must not silently drop a hint). Names are checked against the board by check_advice_refs; entries that have no effect are warnings.

Definition in file advice.hpp.