Web documentation v0.1

docs/source/conf.py

@@ -34,11 +34,13 @@
 # extensions = ['sphinx.ext.duration', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.doctest',
 #               'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig']
 
-extensions = ['autoapi.extension'
+extensions = [
+        'autoapi.extension',
+        'myst_parser'
               ]
 
 # todo_include_todos = True
-source_suffix = '.rst'
+source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'}
 master_doc = 'index'
 add_function_parentheses = True
 

docs/source/eng_guidebook/algorithms.md

@@ -0,0 +1,139 @@
+# Scheduling Algorithms
+
+## How to choose an algorithm
+
+### Heuristic schedulers (HEFT, HEFTBetween, Topological)
+
+- Provide a workable schedule quickly.
+- HEFT/HEFTBetween compute task order and approximate execution times to reduce project makespan.
+- Topological orders tasks by dependencies without complex optimization.
+- HEFT builds a plan from scratch over the entire graph, while HEFTBetween inserts new activities into an already
+  occupied calendar, trying not to reshuffle the previously built plan.
+
+Imports:
+
+```python
+from sampo.scheduler.heft import HEFTScheduler
+from sampo.scheduler.heft import HEFTBetweenScheduler
+from sampo.scheduler.topological import TopologicalScheduler
+```
+
+---
+
+### Genetic scheduler
+
+- Tries many different combinations and often finds a schedule with a shorter project completion time (minimizing project makespan).  
+  Works slower than simpler algorithms.
+- Key parameters:
+    - `number_of_generation` — how many times to improve the solutions (more → higher chance of improvement, but slower).
+    - `size_of_population` — how many alternatives to keep simultaneously (more → more ideas, but slower and more memory-consuming).
+    - `mutate_order` — how often to change the task order (while preserving dependencies)  
+      (higher values → wider search, but slower convergence).
+    - `mutate_resources` — how often to change the allocation of resources/contractors  
+      (higher values → better parallelism, but may cause more “conflicts” if resources are scarce).
+    - Additionally: `work_estimator`, `seed` (for reproducibility).
+
+Example:
+
+```python
+from sampo.scheduler.genetic import GeneticScheduler
+
+scheduler = GeneticScheduler(
+    number_of_generation=50,
+    size_of_population=100,
+    mutate_order=0.1,
+    mutate_resources=0.1
+)
+```
+
+---
+
+## Multi-Agent Scheduling
+
+Splits a project into parts (blocks), schedules them using different strategies, and assembles a global plan.  
+Useful for large projects and for combining strategies (`sampo.scheduler.multi_agency`).
+
+### “Auction” without block partitioning
+
+```python
+from uuid import uuid4
+from sampo.generator.base import SimpleSynthetic
+from sampo.scheduler.heft import HEFTScheduler
+from sampo.scheduler.topological import TopologicalScheduler
+from sampo.scheduler.multi_agency.multi_agency import Agent, StochasticManager
+from sampo.schemas.contractor import Contractor
+from sampo.schemas.resources import Worker
+from sampo.generator.environment.contractor_by_wg import get_contractor_by_wg, ContractorGenerationMethod
+
+# 1) Small work graph
+ss = SimpleSynthetic(231)
+wg = ss.work_graph(bottom_border=30, top_border=40)
+
+# 2) Contractor with the required worker types
+kinds = {req.kind for node in wg.nodes for req in node.work_unit.worker_reqs}
+cid = str(uuid4())
+workers = {k: Worker(str(uuid4()), k, 50, contractor_id=cid) for k in kinds}
+contractors = [get_contractor_by_wg(
+    wg,
+    scaler=1.0,  # increase if needed, e.g., 1.2 or 1.5
+    method=ContractorGenerationMethod.AVG,
+)]
+
+# 3) Two agents with different approaches
+agents = [
+    Agent("HEFT", HEFTScheduler(), contractors),
+    Agent("Topological", TopologicalScheduler(), contractors),
+]
+manager = StochasticManager(agents)
+
+# 4) “Auction”: agents propose schedules; pick the best by finish time
+start, end, schedule, winner = manager.run_auction(wg)
+print("Winning agent:", winner.name, "Makespan:", end - start)
+```
+
+### With Block Partitioning
+
+```python
+from random import Random
+from sampo.generator.base import SimpleSynthetic
+from sampo.scheduler.heft import HEFTScheduler
+from sampo.scheduler.topological import TopologicalScheduler
+from sampo.scheduler.multi_agency.multi_agency import Agent, StochasticManager
+from sampo.scheduler.multi_agency.block_generator import generate_blocks, SyntheticBlockGraphType
+
+# 1) Build a "block graph" (each block is its own small WorkGraph)
+seed = 231
+rand = Random(seed)
+bg = generate_blocks(
+    SyntheticBlockGraphType.RANDOM,
+    n_blocks=4,
+    type_prop=[1, 1, 1],
+    count_supplier=lambda i: (10, 15),
+    edge_prob=0.3,
+    rand=rand
+)
+
+# 2) Contractors for agents
+ss = SimpleSynthetic(rand)
+contractor_a = ss.contractor(40)
+contractor_b = ss.contractor(40)
+
+# 3) Agents with different algorithms
+agents = [
+    Agent("HEFT", HEFTScheduler(), [contractor_a]),
+    Agent("Topo", TopologicalScheduler(), [contractor_b]),
+]
+manager = StochasticManager(agents)
+
+# 4) Schedule blocks in order, respecting inter-block dependencies
+scheduled_blocks = manager.manage_blocks(bg)
+
+# 5) Summary: who took which block and when it ran
+print("Scheduled blocks:")
+for block_id, sblock in scheduled_blocks.items():
+    print(f"Block {block_id}: agent={sblock.agent.name}, "
+          f"start={sblock.start_time}, end={sblock.end_time}, duration={sblock.duration}")
+
+project_finish = max(sb.end_time for sb in scheduled_blocks.values())
+print("Project finish time:", project_finish)
+```

docs/source/eng_guidebook/connections.md

@@ -0,0 +1,75 @@
+# Task Dependencies
+
+## Terms
+
+- **Dependency** — an arrow between tasks that defines when the next one can start.
+- **Lag** — the amount of time that must pass after one task before starting the next.
+- **IFS (Interruption-Free Sequence)** — a sequence of consecutive tasks performed without breaks by the same workers.
+
+> **Why it matters (IFS):** It models a continuous block of work, ensuring that tasks performed by the same workers
+> follow
+> one another without any interruptions or delays. This is crucial for processes where stopping between steps is
+> technologically undesirable or inefficient.
+
+---
+
+## Dependency Types
+
+| Type | How to read                | Meaning (short)                                                 |
+|------|----------------------------|-----------------------------------------------------------------|
+| FS   | Finish → Start             | B can start after A finishes (+ lag, if any)                    |
+| FFS  | Finish → Start (with lag)  | Same as FS, but with a mandatory pause                          |
+| IFS  | Continuous: Finish → Start | B starts immediately after A with no break, by the same workers |
+| SS   | Start ↔ Start              | A and B can start together                                      |
+| FF   | Finish ↔ Finish            | B must finish no earlier than A                                 |
+
+## When to Use Each Type
+
+- Regular sequence of actions: **FS**.
+- Technological pause required: **FFS** (or **FS** with a lag).
+- Continuous work by the same workers without interruption: **IFS**.
+- Simultaneous start of tasks: **SS**.
+- Tasks must finish at the same time: **FF**.
+
+---
+
+## Mini-Examples
+
+1) **FS + lag**  
+   A: “Pour concrete” (finishes on Day 2) → lag 3 days → B: “Wall masonry” (not earlier than Day 5).
+
+2) **IFS**  
+   A: “Drilling” ⇒ B: “Anchoring” ⇒ C: “Post installation” (same workers, no breaks).
+
+3) **SS**  
+   A: “Server startup” ≡ B: “Monitoring launch” (simultaneous start).
+
+4) **FF**  
+   A: “Main configuration” || B: “Documentation” (must finish at the same time).
+
+5) **FFS**  
+   A: “Apply primer” → lag 4 hours → B: “Painting”.
+
+Legend: → (FS/FFS), ⇒ (IFS), ≡ (SS), || (FF).
+
+---
+
+## Example of a CSV File with Dependencies
+
+Suppose we have a file named `predecessors.csv`:
+
+```
+child_id,parent_id,type,lag
+B,A,FS,3
+C,B,IFS,0
+D,C,IFS,0
+E,A,SS,0
+```
+
+Explanation:
+
+- **B** starts after **A** + 3 (lag of 3 days).
+- **C** and **D** together with **B** form a continuous chain (**IFS**).
+- **E** starts together with **A** (**SS**, does not delay the process).
+
+```

docs/source/eng_guidebook/contractors.md

@@ -0,0 +1,127 @@
+# Contractor
+
+## Terms
+
+- **Worker Requirement (`WorkerReq`)** — defines who and how many people are needed for a task:  
+  profession (`kind`), minimum/maximum number of workers (`min_count…max_count`), and work volume or productivity rate (
+  `volume`).
+- **Worker** — represents human resources: specialization (`name`), quantity (`count`), productivity (`productivity`),  
+  owner (`contractor_id`), and optionally cost per unit (`cost_one_unit`).
+- **Equipment** — a non-human resource: its type and quantity. Tasks use it the same way as workers.
+- **Contractor** — a resource provider, essentially a dictionary of available workers and equipment for the scheduler.
+
+---
+
+## Available Professions:
+
+- 'driver'
+- 'fitter'
+- 'handyman'
+- 'electrician'
+- 'manager'
+- 'engineer'
+
+## How to Define a Contractor
+
+### Manually
+
+```python
+from sampo.schemas.contractor import Contractor
+from sampo.schemas.resources import Worker
+from sampo.schemas.interval import IntervalGaussian
+
+# Example: a contractor with two professions (drivers and fitters)
+contractor = Contractor(
+    workers={
+        # dictionary key 'driver' must match Worker.name='driver'
+        'driver': Worker(
+            id='w1',
+            name='driver',  # profession (must match WorkerReq.kind)
+            count=8,  # number of available workers
+            productivity=IntervalGaussian(1.0, 0.1, 0.5, 1.5)  # average productivity with deviation
+            # cost_one_unit=... optional: cost per unit if cost calculation is required
+            # contractor_id='c1' usually matches Contractor.id (if set manually)
+        ),
+        'fitter': Worker(
+            id='w2',
+            name='fitter',
+            count=6,
+            productivity=IntervalGaussian(1.2, 0.1, 0.8, 1.6)
+        ),
+    },
+    id='c1',
+    name='Contractor A'
+)
+```
+
+**Notes:**
+
+* Dictionary keys in `workers` **must match** each `Worker.name`.
+* The field `WorkerReq.kind` from tasks must match `Worker.name`; otherwise, the scheduler cannot assign workers.
+* The `contractor_id` of each worker usually matches `Contractor.id`.
+* `IntervalGaussian(μ, σ, low, high)` — defines **average productivity (μ)** with standard deviation (σ) and range
+  limits `low…high`.
+
+### Quick resource package generator
+
+```python
+from sampo.generator.base import SimpleSynthetic
+
+ss = SimpleSynthetic()
+contractor = ss.contractor(pack_worker_count=10)
+# pack_worker_count: A scaling factor for the number of workers in each profession
+```
+
+---
+
+### Contractor “from Graph” (based on task requirements)
+
+```python
+from sampo.generator.environment.contractor_by_wg import get_contractor_by_wg, ContractorGenerationMethod
+
+# wg — your WorkGraph with tasks and their WorkerReq
+contractor = get_contractor_by_wg(
+    wg,
+    scaler=1.0,  # scale resource capacities (e.g., 1.5 = +50%)
+    method=ContractorGenerationMethod.AVG  # aggregate requirements by average
+)
+```
+
+**How it works:**
+
+* Analyzes all `WorkerReq` in the project.
+* Aggregates or averages resource needs by job type.
+* Builds a contractor with an appropriate number of workers per profession.
+* The `scaler` parameter lets you quickly increase or decrease available resources without editing them manually.
+
+---
+
+## A Few More Mini-Examples
+
+Two contractors defined separately:
+
+```python
+from sampo.schemas.contractor import Contractor
+from sampo.schemas.resources import Worker
+
+contractor_a = Contractor(
+    id='ca', name='Team A',
+    workers={'welder': Worker(id='wa', name='welder', count=4)}
+)
+
+contractor_b = Contractor(
+    id='cb', name='Team B',
+    workers={'driver': Worker(id='wb', name='driver', count=6)}
+)
+
+contractors = [contractor_a, contractor_b]
+```
+
+Quickly increase resources for an existing one:
+
+```python
+# Previously there were 6 drivers; now there will be 10
+contractor.workers['driver'].count = 10
+```
+
+---

docs/source/eng_guidebook/index.md

@@ -0,0 +1,14 @@
+# Guidebook
+
+```{toctree}
+:maxdepth: 2
+:numbered:
+caption: Guidebook SAMPO
+intro
+quickstart
+work_graph
+connections
+contractors
+algorithms
+```
+