Skip to content

Commit a208961

Browse files
dsmitsdsmits
committed
Added AI generated content
1 parent b92b6db commit a208961

File tree

10 files changed

+3620
-10
lines changed

10 files changed

+3620
-10
lines changed

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
serve:
3+
mkdocs serve

‎docs/README.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# PythonLab Documentation
2+
3+
Welcome to the PythonLab package documentation. PythonLab is a Python framework for defining, parsing, and managing laboratory automation workflows.
4+
5+
## Version
6+
7+
Current version: **0.2.3**
8+
9+
## Table of Contents
10+
11+
1. [Overview](#overview)
12+
2. [Core Concepts](#core-concepts)
13+
3. [Architecture](#architecture)
14+
4. [Getting Started](#getting-started)
15+
5. [Documentation Index](#documentation-index)
16+
17+
## Overview
18+
19+
PythonLab allows you to:
20+
- **Define laboratory workflows** in Python syntax
21+
- **Parse workflows** into directed acyclic graphs (DAGs)
22+
- **Model laboratory resources** (devices, labware, substances, data)
23+
- **Support runtime decision-making** based on experimental measurements
24+
- **Enable workflow scheduling and optimization**
25+
26+
The framework converts laboratory process descriptions into executable workflow graphs that can be analyzed, scheduled, and executed by automation systems.
27+
28+
## Core Concepts
29+
30+
### 1. Processes (`PLProcess`)
31+
32+
A **process** is a Python class that describes a laboratory workflow. It defines:
33+
- What resources are needed (devices, labware, substances)
34+
- The sequence of operations to perform
35+
- How data flows through the workflow
36+
- Runtime decision points based on measurements
37+
38+
### 2. Resources
39+
40+
Resources represent the physical and logical components of laboratory automation:
41+
42+
- **ServiceResource**: Laboratory equipment and software services (incubators, centrifuges, plate readers, etc.)
43+
- **LabwareResource**: Physical containers (plates, tubes, flasks)
44+
- **SubstanceResource**: Chemical and biological materials
45+
- **DataResource**: Data inputs and outputs
46+
47+
### 3. Workflow Graphs
48+
49+
The `PLProcessReader` parses process definitions into NetworkX directed graphs where:
50+
- **Nodes** represent operations, labware, variables, or decisions
51+
- **Edges** represent dependencies and data flow
52+
- **Metadata** includes timing, costs, and constraints
53+
54+
### 4. Runtime vs Compile-Time
55+
56+
**Compile-time** (during parsing):
57+
- Static variables and loops are evaluated
58+
- Workflow structure is determined
59+
- Graph is constructed
60+
61+
**Runtime** (during execution):
62+
- Measurements produce values
63+
- Conditional branches are selected
64+
- Dynamic decisions are made
65+
66+
## Architecture
67+
68+
```
69+
┌─────────────────────────────────────────────────────────────┐
70+
│ PLProcess (Abstract) │
71+
│ - Defines workflow in process() method │
72+
│ - Declares resources in create_resources() │
73+
└────────────────────┬────────────────────────────────────────┘
74+
│
75+
│ parse
76+
▼
77+
┌─────────────────────────────────────────────────────────────┐
78+
│ PLProcessReader │
79+
│ - Extracts source code │
80+
│ - Parses AST │
81+
│ - Builds workflow graph │
82+
└────────────────────┬────────────────────────────────────────┘
83+
│
84+
│ creates
85+
▼
86+
┌─────────────────────────────────────────────────────────────┐
87+
│ PLProcessSimulator │
88+
│ - Inherits from PLProcess │
89+
│ - Contains workflow: nx.DiGraph() │
90+
│ - Tracks labware state │
91+
│ - Manages graph construction │
92+
└─────────────────────────────────────────────────────────────┘
93+
```
94+
95+
## Getting Started
96+
97+
### Basic Example
98+
99+
```python
100+
from pythonlab.resource import ServiceResource, LabwareResource
101+
from pythonlab.process import PLProcess
102+
from pythonlab.pythonlab_reader import PLProcessReader
103+
104+
# Define a custom service
105+
class MyIncubator(ServiceResource):
106+
def incubate(self, labware, duration, temperature, **kwargs):
107+
kwargs.update(dict(
108+
fct='incubate',
109+
duration=duration,
110+
temperature=temperature
111+
))
112+
self.proc.add_process_step(self, [labware], **kwargs)
113+
114+
# Define a process
115+
class SimpleProcess(PLProcess):
116+
def create_resources(self):
117+
self.incubator = MyIncubator(proc=self, name="Incubator1")
118+
self.plate = LabwareResource(proc=self, name="Plate1")
119+
120+
def init_service_resources(self):
121+
super().init_service_resources()
122+
123+
def process(self):
124+
# Define the workflow
125+
self.incubator.incubate(self.plate, duration=3600, temperature=310)
126+
127+
# Parse the process
128+
simulator = PLProcessReader.parse_process(SimpleProcess())
129+
130+
# Visualize the workflow
131+
simulator.visualize_workflow_graph()
132+
133+
# Access the graph
134+
print(f"Nodes: {simulator.workflow.number_of_nodes()}")
135+
print(f"Edges: {simulator.workflow.number_of_edges()}")
136+
```
137+
138+
## Documentation Index
139+
140+
### Guides
141+
142+
1. **[Writing PLProcessReader-Compliant Processes](pythonlab/writing_processes.md)** - Comprehensive guide to implementing processes
143+
2. **[Resource Guide](./resources.md)** - Details on all resource types
144+
3. **[Control Flow and Runtime Decisions](./control_flow.md)** - Handling conditionals and loops
145+
4. **[Workflow Graph Structure](pythonlab/workflow_graph.md)** - Understanding the graph representation
146+
147+
### Reference
148+
149+
1. **[PLProcess API Reference](./api_plprocess.md)** - Complete PLProcess class documentation
150+
2. **[PLProcessReader API Reference](./api_reader.md)** - Parser and simulator documentation
151+
3. **[Built-in Services](pythonlab/builtin_services.md)** - Available ServiceResource implementations
152+
4. **[Examples](pythonlab/examples.md)** - Complete example processes
153+
154+
## Project Structure
155+
156+
```
157+
pythonlab/
158+
├── __init__.py # Package initialization
159+
├── process.py # PLProcess base class
160+
├── resource.py # Resource base classes
161+
├── pythonlab_reader.py # PLProcessReader and PLProcessSimulator
162+
├── processes/ # Process-specific modules
163+
│ ├── liquid_handling/
164+
│ ├── incubation/
165+
│ ├── separation/
166+
│ └── ...
167+
└── resources/ # Resource implementations
168+
├── services/ # ServiceResource implementations
169+
│ ├── incubation.py
170+
│ ├── moving.py
171+
│ ├── centrifugation.py
172+
│ ├── analysis.py
173+
│ └── ...
174+
├── labware/
175+
├── substances/
176+
└── data/
177+
```
178+
179+
## Key Files
180+
181+
- **pythonlab/process.py** - Defines the `PLProcess` abstract base class
182+
- **pythonlab/resource.py** - Defines all resource base classes
183+
- **pythonlab/pythonlab_reader.py** - Contains `PLProcessReader` and `PLProcessSimulator`
184+
185+
## Next Steps
186+
187+
1. Read **[Writing PLProcessReader-Compliant Processes](pythonlab/writing_processes.md)** for a detailed tutorial
188+
2. Explore the **[examples](pythonlab/examples.md)** to see complete implementations
189+
3. Review **[Built-in Services](pythonlab/builtin_services.md)** to understand available devices
190+
191+
## Contributing
192+
193+
When creating new processes:
194+
1. Subclass `PLProcess`
195+
2. Implement all abstract methods
196+
3. Define resources in `create_resources()`
197+
4. Initialize services in `init_service_resources()`
198+
5. Describe workflow in `process()`
199+
200+
## Support
201+
202+
For issues and questions, refer to the project repository or contact the development team.

‎docs/index.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ Things to explain:
88
- what are workers
99
- Things to reuse, things to implement
1010

11-
## Processes
11+
## Pythonlab
12+
PythonLab is a Python framework for defining, parsing, and managing laboratory automation workflows. It allows you to write laboratory processes in Python syntax and converts them into executable workflow graphs.
1213

13-
## Resources
14-
Resources are objects that implement PythonLabs `ServiceResource`. Many are available in pythonlab, but sometimes it might be required to implement a custom one.
1514

1615
## Workers
1716
Worker_adaptation also needs to be custom.
18-
Worker calls steps through the wrappers, and returns the Observable object to orchestrator.
17+
Worker calls steps through the wrappers, and returns the Observable object to orchestrator.
18+
1919

2020
## Wrappers
2121
Wrappers implement calls to actual sila servers. In worker the devices are still just conceptual.
@@ -25,3 +25,6 @@ Sila servers have 2 types of commands, one type is observable, other isn’t. If
2525

2626
## Config file
2727
Describes the capacity of the devices in your lab. This information is read by both the orchestrator and scheduler.
28+
29+
## Disclaimer
30+
This documentation has been written with the help of AI.

0 commit comments

Comments
 (0)