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 box and the flows are corrected there and everything recalculates. Give it too (a free account is needed to download it). metre the take-off of the whole network.
IF A CIRCUIT IS STILL 'calcul', call again with THE SAME ARGUMENTS a moment later. Nothing is recomputed and nothing is billed again: an identical call only reads. A different velocity or flow is applied to the circuits already there, without a new analysis.
HOW TO USE IT WELL.
Ask the user for the design velocity before calling, or say which one you used. THIS TOOL DOES NOT READ THE FLOW FROM THE MODEL: look for it in the air handling unit's properties with read_ifc_overview and pass it as flow_m3h, one unit at a time - see that argument. Failing that, the flow comes from the design velocity: between two branches, the length-weighted average velocity of the straight ducts equals it, and no duct runs more than 20 % above it. Say which of the two it was.
TWO WAYS TO COMPUTE, AND THE USER CHOOSES. Offer them both, in one short sentence each, before computing:
the network AS MODELLED (the default): flows follow the duct sections and never rise along a circuit, as in a sized network. The pressure drops are NOT returned - see below.
a PRELIMINARY network (preliminary_design=true): nothing is sized yet, so each stretch carries what its own ducts carry at the design velocity, the flow may rise along the circuit, and every fitting is computed at that velocity. The pressure drops ARE returned, because they no longer depend on any flow the user must confirm: they say what a correctly sized circuit with these singularities and this length would reach. Quote them only with that sentence attached. Both compute the same circuits, on the same geometry; only the flows differ. The same circuits can be recomputed either way, by calling again with or without preliminary_design.
YOU ARE NOT GIVEN THE PRESSURE DROPS, ON PURPOSE - except in the preliminary mode above. Until the user has confirmed on the page each circuit's type (supply, return, outdoor air, exhaust) and its flows, the pressure drop is wrong - the tool cannot know either. Never estimate, quote or compute one yourself, not even roughly: say the pressure drops are on the page, once the type and the flows are confirmed.
Every circuit is computed as a SUPPLY circuit until someone says otherwise: the tool cannot tell supply from return. The flow rates do not depend on it - a duct carries what its section allows either way - but the tee coefficients and the design velocity do. If a branch is a return, an intake or an exhaust, SAY SO and tell the user how to set it in the 3D view: hovering the arrow of a circuit shows its type, and each click on that label moves to the next one - supply, return, outdoor air, exhaust. A click on the arrow itself reverses the air direction, which is how the user says at which end the terminal or the louvre sits when the duct has a constant section.
Say that each circuit was chosen BY LENGTH. A shorter path loaded with dampers, bends or silencers can lose more pressure.
BEFORE THE LINK, SAY WHAT THE USER MUST CONFIRM ON THE PAGE - see 'A_CONFIRMER_PAR_L_UTILISATEUR', circuit by circuit: whether each network is supply, return, outdoor air or exhaust (all are computed as supply until the user says otherwise), and the flows (which are estimates from the velocity, which were given). Never leave it out: the figures mean nothing until both are confirmed.
END YOUR ANSWER WITH THE 3D LINK, on its own line, and urge the user to open it - see 'A_DONNER_A_L_UTILISATEUR'. Name each circuit by its unit, its colour and its type - several circuits share a colour. The page is where the calculation is finished: the user sets the flows (a click on the unit, or typed in the table), the velocity, the air direction and the circuit type, deletes a circuit from its tab - its colour goes with it -, adds one by clicking a start and an end part, and downloads the workbook, one editable sheet per circuit.
A FLOW THAT LOOKS WRONG IS AN ESTIMATE, NOT A DEFECT. When none was given, flows come from the design velocity. If you point one out, say in the same breath that the user sets it on the page or in the workbook - see 'debits_et_reglages'.
THE USER'S CHOICES STAND. A circuit they deleted is not computed again: it comes back under 'retires_par_l_utilisateur', and only they can restore it, by tracing it on the page. A circuit they traced by hand is never replaced. So after they have been on the page, call this again before stating any figure - never answer from memory.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The model token, from ifc_upload_result or from the link the user pasted. | |
| units | No | 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. | |
| end_guid | No | 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. | |
| flow_m3h | No | 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 %. | |
| unit_name | No | 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. | |
| start_guid | No | 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. | |
| start_role | No | 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. | |
| all_networks | No | 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. | |
| network_guid | No | 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. | |
| excluded_guids | No | 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. | |
| max_velocity_m_s | No | 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. | |
| preliminary_design | No | 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. |