trace_duct_circuits
THE CIRCUITS THE FANS OF A MODEL ARE SIZED ON, found without anyone
clicking and computed on the pressure-drop page, where the user
confirms types and flows and reads the pressure drops.
THE USER WANTS TO PICK THE UNITS THEMSELVES: call this tool with ONLY
the token right away, and give them 'lien_centrales' - the control
page, where a click turns a unit red and 'Send to my AI' sends you
their choice.
Without that link they have nowhere to select.
ONLY UNITS AND FANS ARE EXCHANGED. The tool never sends you system
names: it sends the air handling units and fans your rules found,
each with what the network walk finds connected to it - geometry,
not names. A unit is equipment with a FAN - air handling unit,
monobloc, ventilation casing, fan. Coils, heat exchangers, filters,
silencers, dampers are network pieces: if one shows up in the list
(often as 'dans_le_reseau_de' another unit), your rules are too
wide - fix them with apply_ifc_rules before choosing. But a family
NAMED as a unit (CTA, AHU, monobloc) is one, whatever its type says.
A LOW 'raccordement' MOSTLY MEANS MISSED UNITS: look for families
named CTA, AHU, monobloc, caisson that got no unit role, and add
them before sending the user anywhere.
FIRST THE CHECK AND THE LIST, THEN THE CALCULATION. Called with only
the token, once your rules are posted with apply_ifc_rules, it
computes NOTHING and bills nothing. It walks the networks from every
unit and fan and measures the share of the model's air pieces they
reach ('raccordement'). Two answers:
- CONNECTED (half of the air pieces or more): the COMPLETE list of
units and fans ('centrales_et_ventilateurs', each with its
number of connected networks) and 'lien_centrales', the
CONTROL PAGE ('Network check' in English, 'Contrôle des
réseaux' in French) - not a view-only page: every unit in its colour
with its networks, where the user checks and CORRECTS the
connections (identify or remove a unit, add a virtual AHU,
connect or separate two parts, cross a shared plenum) before
anything is computed. Ask them to check it FIRST and wait for
their answer. There they can also open the calculation page
directly, or CLICK the units to compute: they turn red, and 'Send
to my AI' copies a new link carrying that choice. Give the
user that link, say nothing is computed yet, and that they can
tick there or name the units here. Then:
* the answer carries 'choix_de_l_utilisateur' (the user
ticked on the page): compute EXACTLY those names with
units, as its 'consigne' says - do not ask them again;
* the user named units, even loosely: map their words onto
the EXACT names of the list, say which you picked, and call
again with units;
* the user asked for the whole model and the list says
'tous_possible' (50 air networks or fewer): call again with
all_networks=true;
* otherwise show the user the WHOLE list to tick - every unit
and fan, however long; never only the main ones. 'Tous'
first when it is offered, then one numbered line per unit
with its number of connected networks; mark the units
connected to nothing. Filter only on what the user said,
and then say which filter and how many lines it left out.
Call with what they tick.
- NOT CONNECTED ('non_raccorde': less than half, or no unit at
all): tell the user the sentence of 'A_DIRE_A_L_UTILISATEUR' -
« Nous n'avons pas pu connecter les centrales de traitement
d'air aux réseaux de votre modèle », in their language - and
suggest the pressure-drop page ('lien_pdc'), where they define
each network themselves by a start and an end. Nothing is
computed. If your rules missed units, fix them and call again.
WHAT IS COMPUTED: for each network connected to a chosen unit or
fan, the LONGEST path. Networks connected to no unit are not
computed here.
BEYOND 50 AIR NETWORKS, THE MODEL IS COMPUTED ONE UNIT AT A TIME.
Each call computes ONE unit - unit_name, or units with a single
name - or the network of ONE piece - network_guid. The whole model,
start_role and several units are refused: nothing is computed, and
the answer says why. Ask the user which unit, or which piece: on the
control page, hovering a piece shows its GUID, and a click ticks a unit.
Units the user ticked on the page ('choix_de_l_utilisateur') are
asked for: compute them one per call, one after the other. Never pick the units
yourself, never go through them all in a row on your own, and never
call in parallel (sub-agents, simultaneous calls): the calls on one
model run one after the other on the server, and parallel calls only
slow the site down for everyone. Call again for the next one the user
asks for; what is computed stays, and is not billed again.
YOU SEE A SAMPLE IN THE OVERVIEW, THE WHOLE MODEL HERE. Never choose
the units from what read_ifc_overview showed you - one example per
type: choose from the list this tool returns.
A REQUEST THE TOOL CANNOT MATCH. Names that match nothing come back
under 'non_reconnus', each with the closest names; the names that
did match are computed. If NOTHING matched - or the GUID or
unit_name is unknown - nothing is computed, whatever the size of
the model: the list comes back, with the closest names under
'non_reconnus' and what went wrong under 'demande_non_satisfaite'.
Correct the names from the list, or ask the user which one they
meant, and call again.
A PIECE INSTEAD OF A UNIT. When the model has no unit, when the
unit the user means was not recognised, or when they simply show a
piece: network_guid computes the network of any piece - the tool
finds where its air starts; end_guid computes one circuit to that
end - from start_guid if given, else from the start the tool finds.
A start found by the tool comes back under 'depart_trouve' with what
made it chosen: say so, and ask the user to check it on the 3D link.
The user gets a GUID by hovering a piece on the control page.
These work on complex models too: they designate one network.
ONE UNIT BY ITS NAME. unit_name computes the unit or
fan of that name, found among all the pieces - units does the same
for several. start_guid starts from
one part - an air handling unit, a fan, a duct - and computes the
network it belongs to, nothing else. The answer says so under 'portee' and
lists the model's other units and fans under 'autres_departs': tell
the user the result is partial.
From each starting part it keeps ONE CIRCUIT PER BRANCH: the longest
path in metres of each branch. From an air handling unit, that is one
circuit per network connected to it - supply, return, intake,
exhaust.
EACH OF THESE CIRCUITS IS COMPUTED, and becomes a circuit of the
model: it has a name, a COLOUR, and a tab on the website. All the
circuits of one unit or fan share THAT UNIT'S colour; on the page,
its networks show in a light version of it, and networks connected
to no unit in grey.
WHAT YOU GET
portee what the call covers: the whole model, one role,
or one part's network only.
circuits one per branch: name, colour, length, its unit,
its current type, the flow used at the start and
where it came from. NO PRESSURE DROP: see below.
autres_arrivees shorter paths, found but NOT computed.
lien_3d the calculation page: every unit's networks in
its colour, its circuits in a deeper shade.
lien_centrales the control page: the units and their networks,
where the user checks and corrects the
connections and ticks the units to compute.
ALWAYS give it, as a full URL, at the top of your
answer - also after a calculation: it is the view
the user needs most. Never describe it without
its link.
lien_classeur the Excel workbook of the computed circuits: the
supply / return
Schema valid · SHA-256 6be441297fb0…
View input schema
{
"type": "object",
"properties": {
"token": {
"description": "The model token, from ifc_upload_result or from the link the user pasted.",
"title": "Token",
"type": "string"
},
"start_guid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Leave EMPTY in general. The piece the AIR LEAVES FROM - an air handling unit, a fan, or the duct end where the air enters: circuits are computed from it. A GlobalId from 'equipements' in the answer of apply_ifc_rules, from read_ifc_networks, from read_ifc_overview (guid_exemple), or clicked by the user on the 3D link. For a piece somewhere IN the network, use network_guid instead: the tool finds the start. With end_guid: the one circuit between the two. Not together with start_role.",
"title": "Start Guid"
},
"end_guid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The END of ONE circuit the user wants - a terminal, a louvre, any duct. With start_guid: the circuit from start to end. Alone: the tool finds the start of that network, as for network_guid. Only this circuit is computed, on the path the network walk takes; it never replaces the circuits found by the tool.",
"title": "End Guid"
},
"network_guid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ANY piece of the network the user wants computed - a duct, a terminal, a fitting - when the model has no unit, when the user's unit was not recognised, or when they simply point at the network. The tool walks from it and finds where the air starts: a unit or fan of your rules touching that network (the closest), else a unit found by its IFC class, else the network's largest free duct end. It then computes THAT network only. The start found comes back under 'depart_trouve'. Alone - not with start_guid, end_guid, a name, units or a role.",
"title": "Network Guid"
},
"start_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Rarely needed. Computes every piece your rules gave this role - centrale_de_traitement_d_air or ventilateur -, like all_networks restricted to one role, and only on a model of 50 air networks or fewer whose units are connected. Prefer units. Not together with start_guid.",
"title": "Start Role"
},
"max_velocity_m_s": {
"anyOf": [
{
"maximum": 12,
"minimum": 0.5,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Design velocity, in m/s, 0.5 to 12. It sets the flow rate at the start of each circuit when flow_m3h is not given, and the flow after each branch: between two branches, the length-weighted average velocity of the straight ducts equals it, and no duct exceeds it by more than 20 %. Ventilation: 4 to 6 in main ducts, 2 to 3 near the terminals. ASK THE USER rather than guessing. Omit: the model default, 5 m/s.",
"title": "Max Velocity M S"
},
"flow_m3h": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Flow rate leaving ONE starting part, m3/h - so give it with start_guid. Over the whole model it would give every unit the same flow, and the call refuses it when there are several: compute the model without it, then call once per unit whose flow you know - its circuits are reused, only their flows change. Every circuit leaving that part carries it on its first stretch, and the flows further on are scaled from it - it sets the real velocity. BEFORE GUESSING, LOOK FOR IT: run read_ifc_overview and read the properties of the air handling unit, the fan or the casing you are starting from - a field named Debit, Flow, Air Flow, Luftmenge or Portata, often under a flow property set. Pass what you find, say where it came from, and convert it to m3/h (a value in m3/s is 3600 times smaller). If the model carries nothing, ASK THE USER rather than inventing one. Omit it only when nobody knows: the flow is then derived from the design velocity: the average velocity of the straight ducts between two branches equals it, none exceeds it by 20 %.",
"title": "Flow M3H"
},
"unit_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only when the user asks about ONE unit or fan: its name, or a part of it - « CTA 12 », « AHU-Supply-L2 ». The tool looks it up among EVERY piece your rules gave the role centrale_de_traitement_d_air or ventilateur, case and accents ignored, all words required. Several matches: all are computed - except beyond 50 air networks, where nothing is computed and the matches come back: send the exact name of one. No match: it is matched like 'units' (close spellings, same numbers); still nothing: NOTHING is computed, and the list comes back with the closest names. Not with start_guid.",
"title": "Unit Name"
},
"units": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. For each network connected to each of them, the longest path is computed. Send the EXACT names when you can: the tool also accepts all the words of a name (« CTA 12 »), a modeller's abbreviation and close spellings - but only with the SAME numbers. Not with start_guid. Beyond 50 air networks: ONE name per call.",
"title": "Units"
},
"all_networks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True computes EVERY unit and fan of the list: the longest path of each network connected to them. Networks connected to no unit are not computed - the user traces them on the calculation page, or gives one of their pieces (network_guid). Offered only when the list answer says 'tous_possible': 50 air networks or fewer, units connected. Use it when the user asked for the whole model or ticked 'Tous'. Refused beyond 50 air networks: that model is computed one unit at a time.",
"title": "All Networks"
},
"preliminary_design": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True when the network is still at a PRELIMINARY stage - not sized yet. Every stretch then carries what its own ducts carry at the design velocity (the flow may rise along the circuit, which a sized network would forbid), and every fitting is computed at that velocity; the flow given at the unit is ignored. This is the ONLY mode where the tool returns pressure drops: they say what a correctly sized circuit with these singularities and this length would reach, not what this network loses. ASK THE USER which of the two they want before calling - see the two modes in this tool's description. Omit it for the normal calculation.",
"title": "Preliminary Design"
},
"excluded_guids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Parts to close, by GlobalId. Closing a part cuts the walk there: whatever was only reached through it leaves the survey. Use it when the network visibly runs too far - through a plenum shared with another installation, for instance.",
"title": "Excluded Guids"
}
},
"required": [
"token"
],
"title": "trace_duct_circuitsArguments"
}