thundergraph-model 1.0.0__tar.gz → 1.2.0__tar.gz

{thundergraph_model-1.0.0 → thundergraph_model-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thundergraph-model
-Version: 1.0.0
+Version: 1.2.0
 Summary: Executable systems modeling in Python
 License-File: LICENSE
 Requires-Python: >=3.11

thundergraph_model-1.2.0/docs/release/v1.2.0.md

@@ -0,0 +1,63 @@
+# v1.2.0 Release Notes
+
+## Breaking changes
+
+The authoring surface for `Part`, `System`, and `Requirement` has been overhauled.
+All old methods listed below are **deleted** — any call site will fail at compile time.
+
+| Deleted method | Replacement |
+|----------------|-------------|
+| `model.part(name, Type)` | `model.composed_of(name, Type)` |
+| `model.requirement_package(name, Type)` | `model.composed_of(name, Type)` |
+| `model.requirement(id, text)` | One `Requirement` subclass per "shall" statement |
+| `model.requirement_input(req, name, ...)` | `model.parameter(name, ...)` on the `Requirement` class |
+| `model.requirement_attribute(req, name, ...)` | `model.attribute(name, ...)` on the `Requirement` class |
+| `model.requirement_accept_expr(req, expr)` | `model.constraint(name, expr=...)` on the `Requirement` class |
+
+`AllocationBinding.input_bindings` is renamed to `AllocationBinding.parameter_overrides`.
+
+---
+
+## New authoring rules
+
+**All element types** (`Part`, `System`, `Requirement`) must call `model.name(str)` exactly
+once in `define()`. A second call or an omission raises `ModelDefinitionError`.
+
+**`Requirement` classes** must additionally call `model.doc(str)` exactly once —
+the "shall" statement for that package.
+
+**`System` classes** may not call `model.attribute(...)` or `model.constraint(...)`.
+Value logic and checks belong on owned `Part` or `Requirement` types.
+`model.parameter(...)` on `System` remains allowed for scenario-level inputs.
+
+---
+
+## New API
+
+### `model.composed_of(name, ChildType)`
+Unified composition primitive for both `Part` and `Requirement` children.
+Returns `PartRef` or `RequirementRef` based on `ChildType`. Raises `ModelDefinitionError`
+for any other type.
+
+### `allocate(..., inputs={...})` now wires `model.parameter` slots
+`inputs` keys are requirement package `parameter` names; values are `AttributeRef` slots
+from the allocated `Part` or `System`. The old `requirement_input` routing is gone.
+
+### `ConstraintResult` tagging
+Every constraint produced by an allocated `Requirement` package now carries
+`requirement_path` and `allocation_target_path`. Filter `RunResult.constraint_results`
+by these fields instead of calling `summarize_requirement_satisfaction` (removed).
+
+---
+
+## Documentation
+
+Four new user guide sections added:
+
+- `end_to_end_guide` — step-by-step walkthrough from `Part` definition to `evaluate`
+- `concepts_parts` — parameters, attributes, constraints, composition, roll-ups, ports
+- `concepts_system` — scenario parameters, allocation wiring, nested requirement trees
+- `concepts_evaluation` — both evaluation paths, `RunResult`, constraint filtering, sweep
+
+Existing pages (`quickstart`, `concepts_requirements`, `faq`, `glossary`) rewritten to
+reflect the new API.

{thundergraph_model-1.0.0 → thundergraph_model-1.2.0}/docs/user_docs/_build/html/_modules/index.html

@@ -195,16 +195,23 @@
   <input type="hidden" name="area" value="default">
 </form>
 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
-  <p class="caption" role="heading"><span class="caption-text">User</span></p>
+  <p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../user/install.html">Install</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user/overview.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user/mental_model.html">Mental Model</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../user/quickstart.html">Quickstart (Concrete Example)</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../user/concepts_requirements.html">Concept: Requirements — parameter / attribute / constraint (DEFAULT)</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../user/end_to_end_guide.html">End-to-End Guide: Building a Complete System</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../user/concepts_parts.html">Concept: Parts</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../user/concepts_system.html">Concept: Systems</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../user/concepts_requirements.html">Concept: Requirements</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../user/concepts_evaluation.html">Concept: Evaluation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user/concepts_external_compute.html">Concept: External Compute (Concrete Binding)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user/faq.html">FAQ</a></li>
 </ul>
+<p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../user/quickstart.html">Quickstart</a></li>
+</ul>
 <p class="caption" role="heading"><span class="caption-text">Developer</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../developer/architecture.html">Developer architecture</a></li>
@@ -226,7 +233,7 @@
 </ul>
 </li>
 </ul>
-<p class="caption" role="heading"><span class="caption-text">Phase 2 Drafts (working pages)</span></p>
+<p class="caption" role="heading"><span class="caption-text">Drafts</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../drafts/what_is_thundergraph_model.html">What ThunderGraph Model Is</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../drafts/execution_pipeline.html">Execution Pipeline (Compile -&gt; Instantiate -&gt; Graph -&gt; Evaluate)</a></li>

{thundergraph_model-1.0.0 → thundergraph_model-1.2.0}/docs/user_docs/_build/html/_modules/tg_model/execution/configured_model.html

@@ -195,16 +195,23 @@
   <input type="hidden" name="area" value="default">
 </form>
 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
-  <p class="caption" role="heading"><span class="caption-text">User</span></p>
+  <p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/install.html">Install</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/overview.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/mental_model.html">Mental Model</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../../user/quickstart.html">Quickstart (Concrete Example)</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_requirements.html">Concept: Requirements — parameter / attribute / constraint (DEFAULT)</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/end_to_end_guide.html">End-to-End Guide: Building a Complete System</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_parts.html">Concept: Parts</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_system.html">Concept: Systems</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_requirements.html">Concept: Requirements</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_evaluation.html">Concept: Evaluation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_external_compute.html">Concept: External Compute (Concrete Binding)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/faq.html">FAQ</a></li>
 </ul>
+<p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/quickstart.html">Quickstart</a></li>
+</ul>
 <p class="caption" role="heading"><span class="caption-text">Developer</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../../developer/architecture.html">Developer architecture</a></li>
@@ -226,7 +233,7 @@
 </ul>
 </li>
 </ul>
-<p class="caption" role="heading"><span class="caption-text">Phase 2 Drafts (working pages)</span></p>
+<p class="caption" role="heading"><span class="caption-text">Drafts</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../../drafts/what_is_thundergraph_model.html">What ThunderGraph Model Is</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../drafts/execution_pipeline.html">Execution Pipeline (Compile -&gt; Instantiate -&gt; Graph -&gt; Evaluate)</a></li>
@@ -914,7 +921,7 @@
         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">tgt</span><span class="p">,</span> <span class="n">ElementInstance</span><span class="p">):</span>
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Allocation target &#39;</span><span class="si">{</span><span class="n">tgt_key</span><span class="si">}</span><span class="s2">&#39; is not an ElementInstance&quot;</span><span class="p">)</span>
 
-        <span class="n">input_bindings</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">ValueSlot</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
+        <span class="n">parameter_overrides</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">ValueSlot</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
         <span class="n">raw_inputs</span> <span class="o">=</span> <span class="n">edge</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;_allocate_inputs&quot;</span><span class="p">)</span>
         <span class="k">if</span> <span class="n">raw_inputs</span><span class="p">:</span>
             <span class="k">for</span> <span class="n">iname</span><span class="p">,</span> <span class="n">spec</span> <span class="ow">in</span> <span class="n">raw_inputs</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
@@ -923,7 +930,7 @@
                 <span class="n">slot</span> <span class="o">=</span> <span class="n">path_registry</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">slot_key</span><span class="p">)</span>
                 <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">slot</span><span class="p">,</span> <span class="n">ValueSlot</span><span class="p">):</span>
                     <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;allocate inputs[</span><span class="si">{</span><span class="n">iname</span><span class="si">!r}</span><span class="s2">] path </span><span class="si">{</span><span class="n">slot_key</span><span class="si">!r}</span><span class="s2"> is not a ValueSlot in registry&quot;</span><span class="p">)</span>
-                <span class="n">input_bindings</span><span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">iname</span><span class="p">)]</span> <span class="o">=</span> <span class="n">slot</span>
+                <span class="n">parameter_overrides</span><span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">iname</span><span class="p">)]</span> <span class="o">=</span> <span class="n">slot</span>
 
         <span class="n">alloc_id</span> <span class="o">=</span> <span class="n">derive_declaration_id</span><span class="p">(</span><span class="n">root_type</span><span class="p">,</span> <span class="s2">&quot;allocate&quot;</span><span class="p">,</span> <span class="o">*</span><span class="n">edge</span><span class="p">[</span><span class="s2">&quot;source&quot;</span><span class="p">][</span><span class="s2">&quot;path&quot;</span><span class="p">],</span> <span class="o">*</span><span class="n">edge</span><span class="p">[</span><span class="s2">&quot;target&quot;</span><span class="p">][</span><span class="s2">&quot;path&quot;</span><span class="p">])</span>
         <span class="n">allocations</span><span class="o">.</span><span class="n">append</span><span class="p">(</span>
@@ -931,7 +938,7 @@
                 <span class="n">stable_id</span><span class="o">=</span><span class="n">alloc_id</span><span class="p">,</span>
                 <span class="n">requirement</span><span class="o">=</span><span class="n">req</span><span class="p">,</span>
                 <span class="n">target</span><span class="o">=</span><span class="n">tgt</span><span class="p">,</span>
-                <span class="n">input_bindings</span><span class="o">=</span><span class="n">input_bindings</span><span class="p">,</span>
+                <span class="n">parameter_overrides</span><span class="o">=</span><span class="n">parameter_overrides</span><span class="p">,</span>
             <span class="p">)</span>
         <span class="p">)</span>
 

{thundergraph_model-1.0.0 → thundergraph_model-1.2.0}/docs/user_docs/_build/html/_modules/tg_model/execution/connection_bindings.html

@@ -195,16 +195,23 @@
   <input type="hidden" name="area" value="default">
 </form>
 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
-  <p class="caption" role="heading"><span class="caption-text">User</span></p>
+  <p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/install.html">Install</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/overview.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/mental_model.html">Mental Model</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../../user/quickstart.html">Quickstart (Concrete Example)</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_requirements.html">Concept: Requirements — parameter / attribute / constraint (DEFAULT)</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/end_to_end_guide.html">End-to-End Guide: Building a Complete System</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_parts.html">Concept: Parts</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_system.html">Concept: Systems</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_requirements.html">Concept: Requirements</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_evaluation.html">Concept: Evaluation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/concepts_external_compute.html">Concept: External Compute (Concrete Binding)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../user/faq.html">FAQ</a></li>
 </ul>
+<p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../user/quickstart.html">Quickstart</a></li>
+</ul>
 <p class="caption" role="heading"><span class="caption-text">Developer</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../../developer/architecture.html">Developer architecture</a></li>
@@ -226,7 +233,7 @@
 </ul>
 </li>
 </ul>
-<p class="caption" role="heading"><span class="caption-text">Phase 2 Drafts (working pages)</span></p>
+<p class="caption" role="heading"><span class="caption-text">Drafts</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../../drafts/what_is_thundergraph_model.html">What ThunderGraph Model Is</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../drafts/execution_pipeline.html">Execution Pipeline (Compile -&gt; Instantiate -&gt; Graph -&gt; Evaluate)</a></li>
@@ -334,16 +341,18 @@
 <div class="viewcode-block" id="AllocationBinding">
 <a class="viewcode-back" href="../../../api/api_execution.html#tg_model.execution.AllocationBinding">[docs]</a>
 <span class="k">class</span><span class="w"> </span><span class="nc">AllocationBinding</span><span class="p">:</span>
-<span class="w">    </span><span class="sd">&quot;&quot;&quot;Resolved ``allocate`` edge from a requirement to a target element.</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;Resolved ``allocate`` edge from a requirement package to a target element.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
-<span class="sd">    input_bindings : dict[str, ValueSlot], optional</span>
-<span class="sd">        Maps :meth:`tg_model.model.definition_context.ModelDefinitionContext.requirement_input`</span>
-<span class="sd">        names to concrete value slots on the allocated subtree.</span>
+<span class="sd">    parameter_overrides : dict[str, ValueSlot], optional</span>
+<span class="sd">        Maps requirement package :meth:`~tg_model.model.definition_context.ModelDefinitionContext.parameter`</span>
+<span class="sd">        names to concrete source value slots.  When present, the graph compiler wires the</span>
+<span class="sd">        corresponding requirement package parameter slots as computed values (sourced from the</span>
+<span class="sd">        mapped slots) rather than as free ``INPUT_PARAMETER`` nodes.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
-    <span class="vm">__slots__</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;input_bindings&quot;</span><span class="p">,</span> <span class="s2">&quot;requirement&quot;</span><span class="p">,</span> <span class="s2">&quot;stable_id&quot;</span><span class="p">,</span> <span class="s2">&quot;target&quot;</span><span class="p">)</span>
+    <span class="vm">__slots__</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;parameter_overrides&quot;</span><span class="p">,</span> <span class="s2">&quot;requirement&quot;</span><span class="p">,</span> <span class="s2">&quot;stable_id&quot;</span><span class="p">,</span> <span class="s2">&quot;target&quot;</span><span class="p">)</span>
 
     <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
@@ -351,12 +360,12 @@
         <span class="n">stable_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
         <span class="n">requirement</span><span class="p">:</span> <span class="n">ElementInstance</span><span class="p">,</span>
         <span class="n">target</span><span class="p">:</span> <span class="n">ElementInstance</span><span class="p">,</span>
-        <span class="n">input_bindings</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">ValueSlot</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+        <span class="n">parameter_overrides</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">ValueSlot</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">stable_id</span> <span class="o">=</span> <span class="n">stable_id</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">requirement</span> <span class="o">=</span> <span class="n">requirement</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">target</span> <span class="o">=</span> <span class="n">target</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">input_bindings</span> <span class="o">=</span> <span class="n">input_bindings</span> <span class="ow">or</span> <span class="p">{}</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">parameter_overrides</span> <span class="o">=</span> <span class="n">parameter_overrides</span> <span class="ow">or</span> <span class="p">{}</span>
 
     <span class="k">def</span><span class="w"> </span><span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
         <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;&lt;AllocationBinding: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">requirement</span><span class="o">.</span><span class="n">path_string</span><span class="si">}</span><span class="s2"> -&gt; </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">target</span><span class="o">.</span><span class="n">path_string</span><span class="si">}</span><span class="s2">&gt;&quot;</span></div>