model
Skill77 starsChanged 20 days agoMITView on GitHub
Linear programming model layer standards — LinearArray expressions and Rows, constraints, costs, decision variables, connection segments, reactive parameter tracking, soft versus hard limits, shadow prices, and the HiGHS solve strategy. Use when working under custom_components/haeo/core/model/, when optimization results look wrong, when the model is infeasible, or when solve time regresses.
6 other projects use a version of this.
Adopted by
Most recently taken up by
- timpulver/openai-image-gentheir own version, first seen Nov 1, 2026
- ilanbm/kpoppertheir own version, first seen Oct 13, 2026
- marcuskrogh/skillstheir own version, first seen Oct 13, 2026
- yuchi423/MCM-ICM_Agent_Skillstheir own version, first seen Aug 23, 2026
- TheLatentSpaceLab/Qubitotheir own version, first seen Apr 1, 2026
- alectimison-maker/MCM-ICM_Agent_Skillstheir own version, first seen Jan 29, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- ilanbm/kpopper★ 12same name
- alectimison-maker/MCM-ICM_Agent_Skills★ 3same name
- marcuskrogh/skills★ 1same name
- TheLatentSpaceLab/Qubito★ 1same name
- yuchi423/MCM-ICM_Agent_Skills★ 1same name
- timpulver/openai-image-gen★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-setupSkill
- config-flowSkill
- coverageSkill
- documentationSkill
- elementsSkill
- explain-planSkill
- integrationSkill
- lintSkill
- manifestSkill
- performanceSkill
- pythonSkill
- release-notesSkill
- scenariosSkill
- testingSkill
- translationsSkill
- update-docsSkill
- update-versionSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 12 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Read tagged power and shadow prices before touching policies or dual values.
- Very specific: line 14
When model behavior or formulation changes, update the corresponding page in docs/modeling/.
- Distinctive: line 18
Use SI-derived units scaled for numerical stability throughout all model calculations:
- Very specific: line 30
Never assume a constant period length — multiply by periods element-wise.
- Very specific: line 59
Create variables with solver.add_variables(count, name=..., lower=..., upper=...), which returns one row per column.
- Very specific: line 68
Start a sum that may have no terms from LinearArray.zeros(count).
- Distinctive: line 72
Use a 0/1 mask or per-period bounds to switch rows on and off, as window masks do.
- Very specific: line 73
When each row reaches several periods of another array with varying coefficients, build the coefficient matrix with numpy and write matrix …
- Distinctive: line 84
No products of variables, no conditionals on variable values, no absolute values without the standard two-variable split.
- Distinctive: line 85
Document the physical meaning of each constraint.
- Distinctive: line 87
Document the economic interpretation of each cost.
- Distinctive: line 88
Use descriptive variable names that reflect physical quantities.
- Distinctive: line 94
Create the slack variables unconditionally and require a price for them, defaulting to zero where the user sets none, so there is no …
- Distinctive: line 118
When a forecast updates, only affected constraints are rebuilt and the solver warm-starts.
- Distinctive: line 133
Every blended plan is checked at its basis: the cost is priced with a zero-iteration solve, and the weight is lowered when the plan is not …
- Distinctive: line 135
Do not remove either check to save time: a stale weight silently trades cost for tie-breaking when too large, and leaves ties to the solver …
- Very specific: line 164
Add cases to core/model/tests/test_data/ rather than writing per-element test functions.
- Distinctive: line 167
Test each element type independently, verify constraints are satisfied in solutions, and cover edge cases such as zero power and full or …
- Distinctive: line 168
If a line cannot be covered by any input case, that is evidence it is unreachable — delete it rather than testing it.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Model layer development
core/model/ is a standalone linear programming library.
It has no Home Assistant imports and import-linter enforces that: it may import only highspy, numpy, and typing_extensions.
Anything needing Home Assistant belongs in the adapter layer.
Mathematical background lives in docs/modeling/.
Read tagged power and shadow prices before touching policies or dual values.
When model behavior or formulation changes, update the corresponding page in docs/modeling/.
Units
Use SI-derived units scaled for numerical stability throughout all model calculations:
- Power: kilowatts (kW)
- Energy: kilowatt-hours (kWh)
- Time: hours (model layer uses hours; rest of codebase uses seconds)
- Price: dollars per kilowatt-hour ($/kWh)
This scaling keeps values in the ideal range for LP solvers. The adapter layer handles conversion between model time (hours) and Home Assistant time (seconds). See units.md for rationale and conversion utilities.
periods is an array of variable-width interval durations, because a horizon's periods need not all be the same length.
Never assume a constant period length — multiply by periods element-wise.
Model elements
The device layer's element types compile down to a small set of model elements, registered in ELEMENTS in core/model/elements/__init__.py.
Each ElementSpec gives the class, its output names, and an arguments hook that builds the constructor arguments.
Its add_order is derived from the class: network elements first, then connections, then elements that read flows.
Network elements produce, consume, or store power and join connections; flow readers read other elements' planned flows to price or constrain them.
collect_model_elements() in core/adapters/registry.py sorts elements by add_order, so flow readers are added after the connections they read.
Network.add() builds each element's constructor arguments with its spec's arguments, which resolves the elements a flow reader names.
A new flow reader needs only its registry entry, not a branch in Network.
Code that needs to tell model elements apart reads the registry, such as whether an element's class subclasses NetworkElement, rather than listing element types.
A single device element expands into several model elements through its adapter's model_elements(), with sub-elements named {main_element}:{subname}.
Elements and connection segments share the ModelComponent base in core/model/component.py, which discovers their @constraint, @cost, and @output methods.
A connection reports each segment's constraints as {segment}_{constraint}, which is how they appear in infeasibility reports.
A network element's roles (is_source, is_sink) and tags are fixed when it is constructed, because they shape power balance rows and per-tag variables created once.
Change them by building a new network, not by assigning to an existing element.
Adding a physical behavior rarely means a new model element type.
Connections are composed of segments, so a new kind of loss, limit, or charge is a new Segment subclass added to the chain rather than a branch inside Connection.
Writing expressions
Expressions are LinearArray values from core/model/linear.py: one row per period, held as column index and coefficient matrices.
Build every constraint and cost from whole-horizon arrays, never one Python object or loop iteration per period.
The cost of rebuilding the LP then stays flat as the horizon grows, which is what keeps each optimization cycle cheap.
- Create variables with
solver.add_variables(count, name=..., lower=..., upper=...), which returns one row per column. Name each group after the element and quantity it holds, such asf"{self.name}.energy_in". - Combine arrays with
+,-, and*by a scalar or one value per row. A single row such asenergy[0]orstored[-1]broadcasts against per-row values, as in numpy. - Compare with
<=,>=, or==to getRows, which a@constraintmethod returns. Combine several blocks withRows.concat([...]). - Return
expr.free()for rows that do not currently apply, so the LP keeps its shape and the rows can bind later. - A
@costmethod returns a single row:(power * price * self.periods).total(). Constant terms in a cost are allowed; they go to the objective's offset rather than to any column. - Start a sum that may have no terms from
LinearArray.zeros(count);LinearArray.sum_of([])is an error.
Per-period differences are expressed as values, not as different code per period:
- Use a 0/1 mask or per-period bounds to switch rows on and off, as window masks do.
- When each row reaches several periods of another array with varying coefficients, build the coefficient matrix with numpy and write
matrix @ array. Zero entries add no terms, so a matrix whose reach changes with parameters keeps a fixed LP shape. - Properties of individual columns, such as making a variable integer, are not rows: select the columns by slicing the variable array, as in
start[:1], and read their solver indices from.cols[:, 0].
solver.describe(rows) prints each row as maths over named columns, such as Battery.energy_in[3] - Battery.energy_in[4] <= 0, which is the quickest way to check a constraint.
Printing a LinearArray or Rows directly shows the same rows over solver column indices.
Evaluate an expression in the current solution with expr.value(solver.column_values()).
Constraints and costs
- Express all constraints as linear inequalities or equalities. No products of variables, no conditionals on variable values, no absolute values without the standard two-variable split.
- Document the physical meaning of each constraint.
- Costs must be linear in the decision variables, with positive meaning cost and negative meaning revenue.
- Document the economic interpretation of each cost.
- Use descriptive variable names that reflect physical quantities.
Keep every starting state feasible
The optimization must run from whatever state the inputs report. A limit that live data can already be past, such as a device that has run beyond its energy goal or telemetry above a requirement, is priced rather than forbidden. Create the slack variables unconditionally and require a price for them, defaulting to zero where the user sets none, so there is no structural "forbidden" branch. An overshoot that has already happened then becomes a fixed priced amount that changes no decision.
Hard constraints remain right for genuine physical limits that the inputs cannot exceed, such as a connection's power limit or a battery's 0 to 100% charge range. Where an input can still report a value outside a physical range, as a glitching state of charge sensor can, clamp it at the input rather than relaxing the physics.
Reactive parameter tracking
core/model/reactive/ is what makes re-optimization cheap.
Understand it before editing any element:
TrackedParam— a descriptor. Assigning a new value invalidates exactly the constraints and costs that read it. Declare parameters asTrackedParamclass attributes; values stashed in plain instance attributes are invisible to invalidation.@constraint— declares a constraint method that the network discovers and aggregates.@constraint(output=True, unit=...)also surfaces the constraint's dual as a shadow-price output. A constraint returns the same rows on every call so the LP keeps its shape: rows that do not currently apply are returned without a comparison and become free rows, and returningNoneis an error.@cost— declares a linear cost contribution.@computed— caches a value computed from parameters, such as a segment's transformed flow. Dependencies are recorded per object and invalidation follows them across objects, so a node balance reading a connection's flow is rebuilt when that connection's efficiency changes. Derive expressions that depend on parameters when they are read; an expression captured at construction never updates.@output— declares a named output the adapter layer can map to sensors.
When a forecast updates, only affected constraints are rebuilt and the solver warm-starts. A change that makes every constraint depend on every parameter fails no test — it just makes optimization slow. The period update and warm start tests are the ones that notice.
Optimization
Network.optimize() minimizes cost, then breaks ties between equally cheap plans with a time-preference secondary objective.
Each element contributes to it through secondary_cost(), which only Connection overrides.
It does this with a blended objective, cost plus a calibrated weight times the secondary, checked after each solve.
This exists so repeated solves warm-start cleanly and shadow prices come from the same basis as the plan.
Degenerate LPs have many optimal solutions; the secondary objective is what stops sensor values jittering between equally optimal plans.
- The plan must match the lexicographic optimum; shadow prices may differ between formulations, since which binding constraint carries a dual is not controllable.
_lexicographic_referencein the network tests computes that optimum exactly, minimizing the cost and then the secondary with the cost bounded, for tests to compare against. - Every blended plan is checked at its basis: the cost is priced with a zero-iteration solve, and the weight is lowered when the plan is not cost-optimal. The secondary's reduced costs are the blended ones minus the cost's, divided by the weight, and the weight is raised when a cost-free move improves the secondary, but never to a weight that failed the cost in the same optimization. Do not remove either check to save time: a stale weight silently trades cost for tie-breaking when too large, and leaves ties to the solver path when too small.
- The time-preference weights must not be a sum of a connection term and a time term alone, or swaps between connections across periods tie exactly.
The fixed offset from
tie_break_offsetprevents that. - Catch optimization failures gracefully and return appropriate status indicators.
- Tell an overshoot the plan should adapt to apart from a plan that is impossible. A limit live data can realistically go past, such as an EV driving beyond its estimated target, is a failure to plan; price it with a slack variable, as Keep every starting state feasible describes. A plan that asks for what the system physically cannot do, such as more power than every source can supply, is impossible; it goes through the failure path rather than slack variables that every feasible solve would pay for.
- An infeasible solve raises
InfeasibleErrorat once, since no blend weight can make it feasible.core/model/infeasibility.pynames the conflicting rows from HiGHS's irreducible infeasible subsystem, and relaxes the model when the network is built withrelax_infeasible. The relaxed amounts it reports are read from the plan the relaxed solve delivers, not from the relaxation's own values, since the plan can stay inside a widened bound. - Log solver diagnostics at debug level.
Policy compilation
core/adapters/policy_compilation.py implements source-to-destination pricing by tagging power with VLAN-like tags.
compile_policies() mutates element configs in place, adding tag fields, and generates policy pricing elements.
It is a required step, not an optional one: connections take their tags as a required argument, so elements must be compiled before they are added.
Build networks with build_network() in core/adapters/network_builder.py, which collects every adapter's model elements, compiles policies, and adds the result; the coordinator and the diagnostics CLI both use it.
The coordinator also calls build_element_updaters() for the updaters that apply changed inputs to the built network.
Testing
Model tests are data-driven.
Add cases to core/model/tests/test_data/ rather than writing per-element test functions.
Each element module defines VALID_CASES, each with a factory, its data, the inputs that fix or bound its power, and the expected_outputs; __init__.py gathers them, with the segment and connection scenarios, for the parametrized tests.
Test each element type independently, verify constraints are satisfied in solutions, and cover edge cases such as zero power and full or empty batteries. If a line cannot be covered by any input case, that is evidence it is unreachable — delete it rather than testing it.
For end-to-end verification of an optimizer change, run the scenario suite and read the snapshot diff.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

