Skip to content

Commit 392561b

Browse files
SeanMcOwenSeanMcOwen
authored
Merge pull request #75 from BlockScience/docs
Docs
2 parents 877b1df + e76876e commit 392561b

File tree

10 files changed

+233
-131
lines changed

10 files changed

+233
-131
lines changed

‎README.md‎

Lines changed: 27 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -2,138 +2,43 @@
22

33
The "Block Diagram Protocol Library" or bdp-lib for short is a library for instantiating and validating fundamental block diagrams. Additional functionalities and enhancements come out of libraries which use it as the base object.
44

5+
**For full documentation please use this bdp-lib site [here](https://blockscience.github.io/bdp-lib/)**
6+
57
## Functional Requirements
68

79
1. The library provides a schema for defining out the elements of a basic block diagram.
810
2. The library can be extended with two primitive functionalities:
11+
912
A. Modifying - Support for basic zooming, tearing and linking functions while not breaking validity rules
13+
1014
B. Enriching - Attatching further enhancements such as types, units, semantic labels, etc.
1115
3. The library performs validation for the following constraints:
16+
1217
A. All inputs follow the schemas supplied
18+
1319
B. All references (through IDs) are present
20+
1421
C. All ports/domains have one and only one input
22+
1523
D. [Optional] All blocks are connected to at least one other block
1624

17-
## Component Definitions
18-
19-
### Space
20-
21-
A space represents the values passed between blocks.
22-
23-
### Block
24-
25-
A block represents a unit of computation or action
26-
27-
### Concrete Block
28-
29-
A concrete block is a specific instance of a block
30-
31-
### Wiring
32-
33-
A relationship that goes from one blocks codomain to another blocks domain
34-
35-
### System
36-
37-
Defines out the spaces, blocks, concrete blocks and wirings used in a system
38-
39-
## JSON Spec
40-
41-
The JSON spec is held within docs/JSON-Spec, schema.md has the high level schema and then individual components are further defined in the linked files in great detail. That being said, the following is the underlying schema in terms of purely types.
42-
43-
## Example bdp-lib Input
44-
45-
```{
46-
"Spaces": [
47-
{"ID": "S1", "Name": "Space A", "Description": "A space"},
48-
{"ID": "S2", "Name": "Space B", "Description": "Another space"},
49-
{"ID": "S3", "Name": "Space C", "Description": "A third space"},
50-
],
51-
"Blocks": [
52-
{
53-
"ID": "B1",
54-
"Name": "Block A",
55-
"Description": "A block",
56-
"Domain": ["S1"],
57-
"Codomain": ["S2"],
58-
},
59-
{
60-
"ID": "B2",
61-
"Name": "Block B",
62-
"Description": "Another block",
63-
"Domain": ["S1"],
64-
"Codomain": ["S3"],
65-
},
66-
{
67-
"ID": "B3",
68-
"Name": "Block C",
69-
"Description": "A third block",
70-
"Domain": ["S2", "S3"],
71-
"Codomain": ["S1", "S1"],
72-
},
73-
],
74-
"ConcreteBlocks": [
75-
{
76-
"ID": "CB1",
77-
"Name": "Concrete Block A",
78-
"Description": "A concrete block",
79-
"Parent": "B1",
80-
},
81-
{
82-
"ID": "CB2",
83-
"Name": "Concrete Block B",
84-
"Description": "Another concrete block",
85-
"Parent": "B2",
86-
},
87-
{
88-
"ID": "CB3",
89-
"Name": "Concrete Block C",
90-
"Description": "A third concrete block",
91-
"Parent": "B3",
92-
},
93-
],
94-
"Wires": [
95-
{
96-
"ID": "W1",
97-
"Parent": "S2",
98-
"SourceBlock": "CB1",
99-
"TargetBlock": "CB3",
100-
"SourceIndex": 0,
101-
"TargetIndex": 0,
102-
},
103-
{
104-
"ID": "W2",
105-
"Parent": "S3",
106-
"SourceBlock": "CB2",
107-
"TargetBlock": "CB3",
108-
"SourceIndex": 0,
109-
"TargetIndex": 1,
110-
},
111-
{
112-
"ID": "W3",
113-
"Parent": "S1",
114-
"SourceBlock": "CB3",
115-
"TargetBlock": "CB1",
116-
"SourceIndex": 0,
117-
"TargetIndex": 0,
118-
},
119-
{
120-
"ID": "W4",
121-
"Parent": "S1",
122-
"SourceBlock": "CB3",
123-
"TargetBlock": "CB2",
124-
"SourceIndex": 1,
125-
"TargetIndex": 0,
126-
},
127-
],
128-
"Systems": [
129-
{
130-
"ID": "Sys1",
131-
"Name": "System A",
132-
"Description": "A system",
133-
"ConcreteBlocks": ["CB1", "CB2", "CB3"],
134-
"Wires": ["W1", "W2", "W3", "W4"],
135-
}
136-
],
137-
}
138-
```
13925

26+
## Conceptual Framework
27+
28+
The conceptual framework distinguishes abstract patterns that we reuse from concrete components which satisfy those patterns. The abstract patterns tell us how things can be wired together but they cannot themselves be wired, only their concrete counterparts can be wired. By preserving these seperation we can identify and take advantage of stuctural similarities in the systems we're modeling.
29+
30+
The following table categorizes components into **abstract vs. concrete** and **structural vs. behavioral** dimensions:
31+
32+
| | Abstract | Concrete |
33+
|--------------|-----------|-----------|
34+
| **Structure** | Space | Wire |
35+
| **Behavior** | Block | Processor |
36+
37+
This classification provides a clear distinction between the elements of the system:
38+
39+
- **Abstract Structure (Space)**: Represents the conceptual spaces through which data, signals, or states flow.
40+
- **Abstract Behavior (Block)**: Defines reusable templates describing how components behave in a system.
41+
- **Concrete Structure (Wire)**: Connects instantiated components (processors) according to defined spaces.
42+
- **Concrete Behavior (Processor)**: An instance of a block that interacts within the system based on its structure.
43+
44+
In summary, **spaces and blocks define the abstract model**, while **wires and processors bring it into concrete implementation** through instantiation and connectivity.

‎docs/Canonical Examples.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Canonical Examples
3+
nav_order: 4
4+
layout: default
5+
---
6+
7+
## Toy Models (WORK IN PROGRESS NOT READY)
8+
9+
### 1. Simple Dynamical System Plant
10+
- **Description**: A basic model demonstrating a single processor with a feedback loop.
11+
- **Model JSON**: [simple_model.json](models/simple_model.json)
12+
13+
### 2. Closed-Loop Control System
14+
- **Description**: A model illustrating a closed-loop control system with a plant, controller, and sensor.
15+
- **Model JSON**: [control_loop_model.json](models/control_loop_model.json)
16+
17+
### 3. Two-Player Game Model
18+
- **Description**: A model representing a two-player game with strategies and payoffs.
19+
- **Model JSON**: [game_model.json](models/game_model.json)
20+
21+
### 4. Adaptive Strategy Model
22+
- **Description**: This model introduces an adaptive strategy where the decision-making process incorporates learning from past experiences to refine the policy over time.
23+
- **Model JSON**: [adaptive_strategy.json](models/adaptive_strategy.json)
24+
25+
### 5. Iterated Game with Learning
26+
- **Description**: An extension of the two-player game model where both players employ adaptive strategies, allowing them to learn and evolve their strategies over multiple iterations.
27+
- **Model JSON**: [iterated_game_with_learning.json](models/iterated_game_with_learning.json)
28+
29+
## Full Models
30+
31+
- Placeholder for future full models represented in separate repositories

‎docs/Functions & Validation Rules.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Functions & Validation Rules
3+
nav_order: 3
4+
layout: default
5+
---

‎docs/Glossary/Toolbox.md‎

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,51 @@
22
title: Toolbox
33
nav_order: 1
44
layout: default
5-
parent: Glossary
6-
---
5+
parent: Schema & Glossary
6+
---
7+
8+
WORK IN PROGRESS - NOT READY
9+
10+
# Toolbox
11+
12+
A toolbox is full of abstract objects that can be thought of as reusable patterns or templates that the concrete components in a workbench satisfy.
13+
14+
A toolbox consists of:
15+
- **Blocks**: Reusable templates for system components.
16+
- **Spaces**: Defines the types of inputs and outputs.
17+
18+
## Schema
19+
20+
The top level schema of a toolbox is:
21+
22+
```json
23+
{
24+
"ID": "string (required)",
25+
"Name": "string (required)",
26+
"Description": "string (optional)"
27+
}
28+
```
29+
30+
And the children schemas are as follows below.
31+
32+
### Block Schema
33+
34+
```json
35+
{
36+
"ID": "string (required)",
37+
"Name": "string (required)",
38+
"Description": "string (optional)"
39+
}
40+
```
41+
42+
### Space Schema
43+
44+
```json
45+
{
46+
"ID": "string (required)",
47+
"Name": "string (required)",
48+
"Description": "string (optional)",
49+
"Domain": "array[Space] (required, can be empty)",
50+
"Codomain": "array[Space] (required, can be empty)"
51+
}
52+
```

‎docs/Glossary/Workbench.md‎

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,69 @@
22
title: Workbench
33
nav_order: 2
44
layout: default
5-
parent: Glossary
6-
---
5+
parent: Schema & Glossary
6+
---
7+
8+
WORK IN PROGRESS - NOT READY
9+
10+
# Workbench
11+
12+
A workbench consists of the concrete components implemented from the abstract components of the toolbox.
13+
14+
15+
## Schema
16+
17+
The top level schema of a workbench is:
18+
19+
```json
20+
{
21+
"ID": "string (required)",
22+
"Parent": "block_id (required)",
23+
"Name": "string (required)",
24+
"Description": "string (optional)",
25+
"Ports": "array[Space] (must match parent block Domain)",
26+
"Terminals": "array[Space] (must match parent block Codomain)"
27+
}
28+
```
29+
30+
And the children schemas are as follows below.
31+
32+
### Processor Schema
33+
34+
35+
```json
36+
{
37+
"ID": "string (required)",
38+
"Parent": "block_id (required)",
39+
"Name": "string (required)",
40+
"Description": "string (optional)",
41+
"Ports": "array[Space] (must match parent block Domain)",
42+
"Terminals": "array[Space] (must match parent block Codomain)"
43+
}
44+
```
45+
46+
### Wire Schema
47+
48+
```json
49+
{
50+
"ID": "string (required)",
51+
"Parent": "space_id (required)",
52+
"Name": "string (optional)",
53+
"Description": "string (optional)",
54+
"Source": "tuple(processor_id, int) (must be valid terminal)",
55+
"Destination": "tuple(processor_id, int) (must be valid port)"
56+
}
57+
```
58+
59+
### System Schema
60+
61+
```json
62+
{
63+
"ID": "string (required)",
64+
"Parent": "space_id (required)",
65+
"Name": "string (optional)",
66+
"Description": "string (optional)",
67+
"Source": "tuple(processor_id, int) (must be valid terminal)",
68+
"Destination": "tuple(processor_id, int) (must be valid port)"
69+
}
70+
```

‎docs/Glossary/Workbench/Processor.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,12 @@ title: Processor
33
nav_order: 1
44
layout: default
55
parent: Workbench
6-
---
6+
---
7+
8+
WORK IN PROGRESS - NOT READY
9+
10+
# Processor
11+
12+
## Schema
13+
14+
## Composite Processor

‎docs/Glossary/Workbench/System.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,6 @@ title: System
33
nav_order: 3
44
layout: default
55
parent: Workbench
6-
---
6+
---
7+
8+
WORK IN PROGRESS - NOT READY

‎docs/Glossary/Workbench/Wire.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,6 @@ title: Wire
33
nav_order: 2
44
layout: default
55
parent: Workbench
6-
---
6+
---
7+
8+
WORK IN PROGRESS - NOT READY

docs/Glossary.md renamed to docs/Schema & Glossary.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Glossary
2+
title: Schema & Glossary
33
nav_order: 2
44
layout: default
55
---

0 commit comments

Comments
 (0)