kschappell/py-dvt-ate
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Restructure package for domain-driven design

Browse Source 
Reorganise package structure to improve separation of concerns:
- instruments/ - SCPI, transport, drivers, interfaces, factory
- simulation/ - physics engine, virtual instruments, server
- framework/ - test runner, logger, limits, context
- tests/ - thermal/, electrical/ (DVT test implementations)
- data/ - repository, models
- reporting/ - generator, templates
- app/ - CLI, config, dashboard

This structure enables:
- Reusable instruments package for other test suites
- Clear separation of simulation (dev) vs production code
- Domain-focused package organisation

Updated documentation to reflect new paths.
This commit is contained in:
Kai Chappell
2025-12-02 01:53:33 +00:00
parent 111666945e
commit 99f70bb23b
29 changed files with 332 additions and 361 deletions
Download Patch File Download Diff File Expand all files Collapse all files

443
docs/02_technical_specification.md
View File

@@ -214,7 +214,7 @@ For **why** decisions were made, see `03_architecture_decisions.md`.
### 2.1 Directory Layout
```
thermaulate/
py_dvt_ate/
├── pyproject.toml # Project metadata and dependencies
├── README.md # Project overview and quick start
├── CHANGELOG.md # Version history
@@ -222,205 +222,163 @@ thermaulate/
├── docs/
│ ├── 01_requirements.md # Business Requirements
│ ├── 02_technical_specification.md # Technical Design (this doc)
│ └── 03_architecture_decisions.md # Architecture Decisions
│ ├── 03_architecture_decisions.md # Architecture Decisions
│ └── 04_development_plan.md # Sprint breakdown
│
├── src/
│ └── thermaulate/
├── src/py_dvt_ate/
│ ├── __init__.py # Package version
│ ├── py.typed # PEP 561 marker
│ │
│ ├── instruments/ # INSTRUMENT CONTROL (reusable)
│ │ ├── __init__.py
│ │ ├── interfaces.py # IThermalChamber, IPowerSupply, IMultimeter
│ │ ├── scpi.py # SCPI parser (shared protocol)
│ │ ├── factory.py # Creates instrument sets from config
│ │ ├── transport/ # Connection layer
│ │ │ ├── __init__.py
│ │ │ ├── base.py # Transport protocol
│ │ │ ├── tcp.py # TCP socket transport
│ │ │ └── visa.py # PyVISA transport (future)
│ │ └── drivers/ # SCPI driver implementations
│ │ ├── __init__.py
│ │ ├── base.py # Base driver
│ │ ├── chamber.py # Thermal chamber driver
│ │ ├── power_supply.py # PSU driver
│ │ └── multimeter.py # DMM driver
│ │
│ ├── simulation/ # PHYSICS SIMULATION (dev/test only)
│ │ ├── __init__.py
│ │ ├── server.py # TCP server hosting virtual instruments
│ │ ├── physics/ # Physics engine
│ │ │ ├── __init__.py
│ │ │ ├── engine.py # Main simulation loop
│ │ │ ├── thermal.py # Thermal calculations
│ │ │ └── models/ # DUT models
│ │ │ ├── __init__.py
│ │ │ ├── base.py # DUT protocol
│ │ │ └── ldo.py # LDO model
│ │ └── virtual/ # Virtual instrument implementations
│ │ ├── __init__.py
│ │ ├── base.py # Base virtual instrument
│ │ ├── chamber.py # Virtual thermal chamber
│ │ ├── power_supply.py # Virtual PSU
│ │ └── multimeter.py # Virtual DMM
│ │
│ ├── framework/ # TEST FRAMEWORK (reusable)
│ │ ├── __init__.py
│ │ ├── runner.py # Test sequencer
│ │ ├── context.py # Runtime context
│ │ ├── logger.py # Measurement logging
│ │ ├── limits.py # Pass/fail evaluation
│ │ └── models.py # Framework models
│ │
│ ├── tests/ # DVT TEST IMPLEMENTATIONS
│ │ ├── __init__.py
│ │ ├── base.py # Base test class
│ │ ├── thermal/ # Thermal characterisation tests
│ │ │ ├── __init__.py
│ │ │ └── tempco.py # Temperature coefficient test
│ │ └── electrical/ # Electrical characterisation tests
│ │ ├── __init__.py
│ │ └── load_regulation.py # Load regulation test
│ │
│ ├── data/ # DATA PERSISTENCE (shared)
│ │ ├── __init__.py
│ │ ├── repository.py # Data access layer
│ │ └── models.py # Data models
│ │
│ ├── reporting/ # REPORT GENERATION (standalone)
│ │ ├── __init__.py
│ │ ├── generator.py # Report generator
│ │ └── templates/ # Report templates
│ │
│ └── app/ # APPLICATION ENTRY POINTS
│ ├── __init__.py
│ ├── py.typed # PEP 561 marker
│ │
│ ├── physics/ # Physics simulation engine
│ │ ├── __init__.py
│ │ ├── engine.py # Main physics loop
│ │ ├── thermal.py # Thermal domain model
│ │ ├── electrical.py # Electrical domain model
│ │ └── dut/
│ │ ├── __init__.py
│ │ ├── base.py # DUT base class
│ │ └── ldo.py # LDO voltage regulator model
│ │
│ ├── instruments/ # Virtual instrument implementations
│ │ ├── __init__.py
│ │ ├── base.py # Instrument base class
│ │ ├── scpi_parser.py # SCPI command parser
│ │ ├── thermal_chamber.py # Thermal chamber simulator
│ │ ├── power_supply.py # Power supply simulator
│ │ └── multimeter.py # DMM simulator
│ │
│ ├── server/ # Simulation server
│ │ ├── __init__.py
│ │ ├── tcp_server.py # Async TCP server
│ │ └── main.py # Server entry point
│ │
│ ├── transport/ # Communication layer
│ │ ├── __init__.py
│ │ ├── base.py # Transport protocol
│ │ ├── tcp.py # TCP/IP implementation
│ │ └── async_tcp.py # Async TCP implementation
│ │
│ ├── drivers/ # Instrument SCPI drivers
│ │ ├── __init__.py
│ │ ├── base.py # Driver base class
│ │ ├── thermal_chamber.py # Chamber SCPI driver
│ │ ├── power_supply.py # PSU SCPI driver
│ │ └── multimeter.py # DMM SCPI driver
│ │
│ ├── hal/ # Hardware Abstraction Layer
│ │ ├── __init__.py
│ │ ├── interfaces.py # Protocol definitions
│ │ ├── factory.py # Instrument factory
│ │ └── impl/ # HAL implementations
│ │ ├── __init__.py
│ │ ├── thermal_chamber.py
│ │ ├── power_supply.py
│ │ └── multimeter.py
│ │
│ ├── executive/ # Test execution framework
│ │ ├── __init__.py
│ │ ├── sequencer.py # Test sequencer
│ │ ├── context.py # Test context
│ │ ├── logger.py # Test logger
│ │ ├── limits.py # Limit checker
│ │ └── models.py # Domain models
│ │
│ ├── tests/ # DVT test implementations
│ │ ├── __init__.py
│ │ ├── base.py # Test base class
│ │ ├── tempco.py # TempCo characterisation
│ │ └── load_regulation.py # Load regulation test
│ │
│ ├── data/ # Data persistence
│ │ ├── __init__.py
│ │ ├── repository.py # Data access layer
│ │ ├── models.py # Data models
│ │ └── migrations/ # Schema migrations
│ │
│ ├── reporting/ # Report generation (Phase 3)
│ │ ├── __init__.py
│ │ ├── generator.py # Report generator
│ │ ├── pdf.py # PDF output
│ │ ├── html.py # HTML output
│ │ └── templates/ # Report templates
│ │
│ ├── api/ # REST API (Phase 2)
│ │ ├── __init__.py
│ │ ├── main.py # FastAPI app
│ │ └── routes/
│ │ ├── __init__.py
│ │ ├── instruments.py
│ │ ├── tests.py
│ │ └── runs.py
│ │
│ ├── dashboard/ # Streamlit dashboard
│ │ ├── __init__.py
│ │ ├── app.py # Main Streamlit app
│ │ ├── pages/ # Multi-page app
│ │ │ ├── 01_instruments.py
│ │ │ ├── 02_run_test.py
│ │ │ └── 03_results.py
│ │ └── components/ # Reusable UI components
│ │ ├── __init__.py
│ │ └── instrument_panel.py
│ │
│ ├── cli/ # Command-line interface
│ │ ├── __init__.py
│ │ └── main.py # Typer CLI app
│ │
│ └── config/ # Configuration handling
│ ├── cli.py # Command-line interface
│ ├── config.py # YAML loading
│ └── dashboard/ # Streamlit dashboard
│ ├── __init__.py
│ ├── models.py # Pydantic config models
│ └── loader.py # Config file loader
│ └── app.py # Main Streamlit app
│
├── tests/ # Test suite
│ ├── conftest.py # pytest fixtures
│ ├── unit/
│ │ ├── test_physics_engine.py
│ │ ├── test_scpi_parser.py
│ │ ├── test_thermal_model.py
│ │ └── ...
│ └── integration/
│ ├── test_instrument_communication.py
│ ├── test_tempco_sequence.py
│ └── ...
├── tests/ # pytest test suite
│ ├── conftest.py # pytest fixtures
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
│
├── config/ # Configuration files
│ ├── default.yaml # Default configuration
│ └── example_pyvisa.yaml # Example for real hardware
├── config/ # Configuration files
│ └── default.yaml # Default configuration
│
├── docker/
│ ├── Dockerfile.server # Simulation server image
│ ├── Dockerfile.app # Test application image
│ └── docker-compose.yml # Full stack orchestration
│
└── scripts/
├── demo.py # Demo script
└── run_tempco.py # Example test execution
└── docker/ # Docker deployment
├── Dockerfile.server # Simulation server image
├── Dockerfile.app # Test application image
└── docker-compose.yml # Full stack orchestration
```
### 2.2 Package Dependencies
```
thermaulate/
├── cli/ ──────────────────────────────────────────────┐
├── api/ ──────────────────────────────────────────────┤
├── dashboard/ ──────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PRESENTATION │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
├── executive/ ◄───────────────────────────────────────────────┤
├── tests/ ◄───────────────────────────────────────────────┤
├── reporting/ ◄───────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ APPLICATION │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
├── hal/interfaces ◄───────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ DOMAIN (Abstractions) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ implements│ │
│ ▼ │
├── hal/impl ◄───────────────────────────────────────────────┤
├── drivers/ ◄───────────────────────────────────────────────┤
├── transport/ ◄───────────────────────────────────────────────┤
├── data/ ◄───────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ INFRASTRUCTURE │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Dependency Graph:
SIMULATION SERVER (Separate Process):
├── physics/ ◄─── Pure domain logic, no external dependencies
├── instruments/ ◄─── Depends on physics
└── server/ ◄─── Depends on instruments
app/ ──────────────▶ framework/ ──────────────▶ instruments/
│ │ │
│ ▼ │
│ data/ ◀────────────────────────┘
│ ▲
▼ │
reporting/ ──────────────┘
simulation/ ─────────────────────────────────▶ instruments/
Key:
- app/ : CLI, dashboard, config loading (PRESENTATION)
- framework/ : Test runner, logger, limits (APPLICATION)
- instruments/ : Interfaces, drivers, transport, SCPI (DOMAIN)
- data/ : Persistence layer (INFRASTRUCTURE)
- reporting/ : Report generation (standalone)
- simulation/ : Physics engine, virtual instruments (DEVELOPMENT)
```
---
## 3. Module Specifications
### 3.1 Physics Module
### 3.1 Instruments Package
**Responsibility**: Simulate coupled thermal-electrical behaviour.
**Responsibility**: Everything about talking to lab instruments.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| PhysicsEngine | `engine.py` | Main simulation loop, state management |
| ThermalModel | `thermal.py` | Heat transfer calculations |
| ElectricalModel | `electrical.py` | Current/voltage relationships |
| DUTBase | `dut/base.py` | Abstract DUT interface |
| LDOModel | `dut/ldo.py` | LDO voltage regulator implementation |
| Interfaces | `instruments/interfaces.py` | IThermalChamber, IPowerSupply, IMultimeter protocols |
| SCPIParser | `instruments/scpi.py` | Parse SCPI command strings |
| Factory | `instruments/factory.py` | Create instrument sets from config |
| Transport | `instruments/transport/` | TCP, VISA connection layer |
| Drivers | `instruments/drivers/` | SCPI command implementations |
**Command Processing Flow**:
```
High-level call → Driver → SCPI command → Transport → Instrument
```
---
### 3.2 Simulation Package
**Responsibility**: Physics simulation for development without real hardware.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| Server | `simulation/server.py` | TCP server hosting virtual instruments |
| PhysicsEngine | `simulation/physics/engine.py` | Main simulation loop |
| ThermalModel | `simulation/physics/thermal.py` | Heat transfer calculations |
| DUTBase | `simulation/physics/models/base.py` | Abstract DUT interface |
| LDOModel | `simulation/physics/models/ldo.py` | LDO voltage regulator model |
| VirtualChamber | `simulation/virtual/chamber.py` | Virtual thermal chamber |
| VirtualPSU | `simulation/virtual/power_supply.py` | Virtual power supply |
| VirtualDMM | `simulation/virtual/multimeter.py` | Virtual multimeter |
**State Management**:
- Engine maintains global simulation time
@@ -429,108 +387,68 @@ SIMULATION SERVER (Separate Process):
---
### 3.2 Instruments Module
### 3.3 Framework Package
**Responsibility**: SCPI-compliant virtual instrument behaviour.
**Responsibility**: Test execution infrastructure.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| InstrumentBase | `base.py` | Common instrument functionality |
| SCPIParser | `scpi_parser.py` | Parse SCPI command strings |
| ThermalChamberSim | `thermal_chamber.py` | Chamber simulation |
| PowerSupplySim | `power_supply.py` | PSU simulation |
| MultimeterSim | `multimeter.py` | DMM simulation |
**Command Processing Flow**:
```
SCPI String → Parser → Command Object → Instrument Handler → Response
```
| TestRunner | `framework/runner.py` | Sequences test steps |
| TestContext | `framework/context.py` | Runtime context |
| TestLogger | `framework/logger.py` | Measurement logging |
| LimitChecker | `framework/limits.py` | Pass/fail evaluation |
| Models | `framework/models.py` | TestStatus, TestResult, etc. |
---
### 3.3 Transport Module
### 3.4 Data Package
**Responsibility**: Low-level communication.
**Responsibility**: Data persistence for test results.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| Transport Protocol | `base.py` | Abstract transport interface |
| TCPTransport | `tcp.py` | Synchronous TCP implementation |
| AsyncTCPTransport | `async_tcp.py` | Async TCP implementation |
| Repository | `data/repository.py` | Data access layer |
| Models | `data/models.py` | TestRun, Measurement dataclasses |
---
### 3.4 Drivers Module
### 3.5 Reporting Package
**Responsibility**: Instrument-specific SCPI command sets.
**Responsibility**: Report generation from stored data.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| DriverBase | `base.py` | Common driver functionality |
| ThermalChamberDriver | `thermal_chamber.py` | Chamber SCPI commands |
| PowerSupplyDriver | `power_supply.py` | PSU SCPI commands |
| MultimeterDriver | `multimeter.py` | DMM SCPI commands |
| Generator | `reporting/generator.py` | Creates reports from data |
| Templates | `reporting/templates/` | Report templates |
---
### 3.5 HAL Module
### 3.6 App Package
**Responsibility**: Hardware abstraction interfaces.
**Responsibility**: Application entry points.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| Protocols | `interfaces.py` | Abstract interfaces |
| InstrumentFactory | `factory.py` | Creates instrument sets from config |
| HAL Implementations | `impl/*.py` | Concrete HAL classes |
---
### 3.6 Executive Module
**Responsibility**: Test execution orchestration.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| TestSequencer | `sequencer.py` | Run test sequences |
| TestContext | `context.py` | Runtime context |
| TestLogger | `logger.py` | Measurement logging |
| LimitChecker | `limits.py` | Pass/fail evaluation |
| Domain Models | `models.py` | Measurement, Result, etc. |
---
### 3.7 Dashboard Module
**Responsibility**: Real-time visualisation via Streamlit.
**Key Components**:
| Component | File | Purpose |
|-----------|------|---------|
| Main App | `app.py` | Streamlit application entry point |
| Instruments Page | `pages/01_instruments.py` | Live instrument status |
| Run Test Page | `pages/02_run_test.py` | Test execution interface |
| Results Page | `pages/03_results.py` | Historical results viewer |
| Instrument Panel | `components/instrument_panel.py` | Reusable instrument display |
| CLI | `app/cli.py` | Command-line interface (Typer) |
| Config | `app/config.py` | YAML loading, instance creation |
| Dashboard | `app/dashboard/app.py` | Streamlit application |
---
## 4. Interface Definitions
### 4.1 HAL Interfaces
### 4.1 Instrument Interfaces
```python
# thermaulate/hal/interfaces.py
# py_dvt_ate/instruments/interfaces.py
from typing import Protocol, runtime_checkable
@@ -664,7 +582,7 @@ class ITestLogger(Protocol):
### 4.2 Transport Interface
```python
# thermaulate/transport/base.py
# py_dvt_ate/instruments/transport/base.py
from typing import Protocol
@@ -701,7 +619,7 @@ class Transport(Protocol):
### 4.3 Test Interface
```python
# thermaulate/executive/models.py
# py_dvt_ate/framework/models.py
from dataclasses import dataclass, field
from datetime import datetime
@@ -778,12 +696,12 @@ class ITest(Protocol):
### 4.4 Factory Interface
```python
# thermaulate/hal/factory.py
# py_dvt_ate/instruments/factory.py
from dataclasses import dataclass
from typing import Literal
from thermaulate.hal.interfaces import IThermalChamber, IPowerSupply, IMultimeter
from py_dvt_ate.instruments.interfaces import IThermalChamber, IPowerSupply, IMultimeter
@dataclass
@@ -827,22 +745,19 @@ class InstrumentFactory:
@staticmethod
def _create_simulated(config: InstrumentConfig) -> InstrumentSet:
"""Create simulated instruments."""
from thermaulate.transport.tcp import TCPTransport
from thermaulate.drivers.thermal_chamber import ThermalChamberDriver
from thermaulate.drivers.power_supply import PowerSupplyDriver
from thermaulate.drivers.multimeter import MultimeterDriver
from thermaulate.hal.impl.thermal_chamber import ThermalChamberHAL
from thermaulate.hal.impl.power_supply import PowerSupplyHAL
from thermaulate.hal.impl.multimeter import MultimeterHAL
from py_dvt_ate.instruments.transport.tcp import TCPTransport
from py_dvt_ate.instruments.drivers.chamber import ThermalChamberDriver
from py_dvt_ate.instruments.drivers.power_supply import PowerSupplyDriver
from py_dvt_ate.instruments.drivers.multimeter import MultimeterDriver
chamber_transport = TCPTransport(config.simulator_host, config.chamber_port)
psu_transport = TCPTransport(config.simulator_host, config.psu_port)
dmm_transport = TCPTransport(config.simulator_host, config.dmm_port)
return InstrumentSet(
chamber=ThermalChamberHAL(ThermalChamberDriver(chamber_transport)),
psu=PowerSupplyHAL(PowerSupplyDriver(psu_transport)),
dmm=MultimeterHAL(MultimeterDriver(dmm_transport)),
chamber=ThermalChamberDriver(chamber_transport),
psu=PowerSupplyDriver(psu_transport),
dmm=MultimeterDriver(dmm_transport),
)
@staticmethod
@@ -954,7 +869,7 @@ All instruments implement these standard commands:
### 5.5 SCPI Parser Specification
```python
# thermaulate/instruments/scpi_parser.py
# py_dvt_ate/instruments/scpi.py
from dataclasses import dataclass
@@ -1071,7 +986,7 @@ P_diss = (V_in - V_out) × I_load + V_in × I_q
### 6.3 Physics Engine Implementation
```python
# thermaulate/physics/engine.py
# py_dvt_ate/simulation/physics/engine.py
from dataclasses import dataclass
@@ -1256,7 +1171,7 @@ Schema:
### 7.3 Data Repository Interface
```python
# thermaulate/data/repository.py
# py_dvt_ate/data/repository.py (interface)
from typing import Protocol
from uuid import UUID
@@ -1366,14 +1281,14 @@ dut:
# Data storage paths
data:
database_path: "./data/thermaulate.db"
database_path: "./data/py_dvt_ate.db"
measurements_dir: "./data/measurements"
reports_dir: "./data/reports"
# Logging configuration
logging:
level: INFO
file: "./data/logs/thermaulate.log"
file: "./data/logs/py_dvt_ate.log"
format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
# Dashboard (Streamlit)
@@ -1391,7 +1306,7 @@ api:
### 8.2 Pydantic Configuration Models
```python
# thermaulate/config/models.py
# py_dvt_ate/app/config.py (config models)
from pydantic import BaseModel, Field
from typing import Literal
@@ -1449,14 +1364,14 @@ class DUTConfig(BaseModel):
class DataConfig(BaseModel):
database_path: str = "./data/thermaulate.db"
database_path: str = "./data/py_dvt_ate.db"
measurements_dir: str = "./data/measurements"
reports_dir: str = "./data/reports"
class LoggingConfig(BaseModel):
level: str = "INFO"
file: str = "./data/logs/thermaulate.log"
file: str = "./data/logs/py_dvt_ate.log"
format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
@@ -1612,7 +1527,7 @@ class AppConfig(BaseModel):
```toml
[project]
name = "thermaulate"
name = "py_dvt_ate"
version = "0.1.0"
description = "Coupled Physics DVT Simulation Platform"
requires-python = ">=3.11"
@@ -1648,9 +1563,9 @@ dev = [
]
[project.scripts]
thermaulate = "thermaulate.cli.main:app"
thermaulate-server = "thermaulate.server.main:main"
thermaulate-dashboard = "thermaulate.dashboard.app:main"
py_dvt_ate = "py_dvt_ate.cli.main:app"
py_dvt_ate-server = "py_dvt_ate.server.main:main"
py_dvt_ate-dashboard = "py_dvt_ate.dashboard.app:main"
[build-system]
requires = ["hatchling"]