Dev

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI - package coherence
+
+on:
+  push:
+    branches: [ dev, main ]
+  pull_request:
+    branches: [ dev, main ]
+
+jobs:
+  test:
+    name: Test & Validate Package
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.10]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Upgrade pip and install build tools
+        run: |
+          python -m pip install --upgrade pip build setuptools wheel
+
+      - name: Install package (editable)
+        run: |
+          python -m pip install -e .
+
+      - name: Run pip check
+        run: |
+          python -m pip check || true
+
+      - name: Install dev/test tools
+        run: |
+          python -m pip install flake8 pytest
+
+      - name: Lint Python (flake8)
+        run: |
+          # Lint package and tests; keep non-blocking to avoid failing on style
+          flake8 pyplecs tests || true
+
+      - name: Run CLI tests (pytest)
+        run: |
+          # Run only the CLI/unit tests that are platform-independent
+          pytest -q tests/test_installer.py tests/test_entrypoint.py tests/test_install_full.py
+
+      - name: Build distribution (sanity)
+        run: |
+          python -m build --sdist --wheel

.gitignore

@@ -1,15 +1,35 @@
+# Byte-compiled / optimized / DLL files
+# remove __pycache__ for all folders and subfolders
+__pycache__/
+pyplecs/webgui/__pycache__/
+/pyplecs/__pycache__/
+/tests/__pycache__/
+
+# other
+pyplecs.egg-info/
+.pytest_cache/
+.venv/
+
+# remove build artifacts
+/dist
+/build
+*.egg-info
+
+
 /utils/guipropview-x64
 /utils/winlister-x64
 /utils/depends22_x64
 /utils/MacroCreatorPortable/x64/MacroCreator
 /utils/MacroCreatorPortable/x86/MacroCreator
 /utils/gui-inspect-tool-master
 /utils/py_inspect-master
-/pyplecs/__pycache__
-/tests/__pycache__
+
 /utils/MacroCreatorPortable
 tests/OLD/
+
 utils/
-pyplecs.egg-info/
+
 *.old
 .idea/
+
+cache/

README.md

@@ -1,25 +1,193 @@
-[![Build Status](https://travis-ci.com/tinix84/pyplecs.svg?branch=master)](https://travis-ci.com/tinix84/pyplecs)
 
-[![codecov](https://codecov.io/gh/tinix84/pyplecs/branch/master/graph/badge.svg)](https://codecov.io/gh/tinix84/pyplecs)
+# PyPLECS: Python Automation for PLECS Simulations
 
-# Python Plecs Repository
+# PyPLECS
 
-I wrote a python package to automatize the python simulations. In the test_basic.py you can find all the unit test where every test case show a different function of the package pyPlecs. Just short summary of capabilities:
+Advanced automation for PLECS simulations with a web UI, REST API, and orchestration tools.
 
-1. test03_plecs_app_open_highpriority: python open plecs as process in highpriority to execure faster simulations
-2. test04_pyplecs_xrpc_server: python use the normal remote control to execute plecs with xrpc server
-3. test07_sequential_simulation_server_different_file: pyPlecs generate different plecs file for every variant request and launch them sequentially with normal xrpc simulations
-4. test09_gui_simulation: pyPlecs generate different plecs file for every variant request and open them all at the same time and execute them in parallel with just one user (interacting with plecs GUI)
+This repository contains the PyPLECS core library, a FastAPI-based web GUI for monitoring and controlling simulations, and helper installers/scripts to bootstrap a development or deployment environment.
 
-Next development steps are:
+## Key features
 
-1. creation of requirement.txt and setup.py to automatize installation
-2. creation of a pool of simulation to manage multiprocessing or multithreading
-3. new example for more complex simulation with gui in Ipython
-4. generation montecarlo variants in python and then analysis in plecs 
+- Automated orchestration of PLECS simulations (sequential and parallel)
+- FastAPI web GUI with WebSocket real-time updates
+- Cache system for simulation results (file-based / parquet)
+- CLI helper `pyplecs-setup` for configuration and environment checks
+- Windows installer script to create a `.venv`, install deps and configure the PLECS executable path
 
-If you want to use but you find bugs please let me know...
+## Requirements
+
+- Python 3.8+ (3.10+ recommended)
+- On Windows: PowerShell / pwsh available for installer scripts
+- PLECS (external, optional) if you want to run GUI-driven simulations
+
+Core Python dependencies are listed in `requirements.txt` and in `pyproject.toml`.
+
+## Installation
+
+Two main ways to prepare the project environment: automated (Windows) or manual (cross-platform).
+
+### Automated (Windows) installer
+
+The repository includes an advanced installer at `tools/installers/windows_installer.ps1` that will:
+
+- Create a `.venv` in the project root
+- Install required Python packages into the venv
+- Probe common PLECS install locations and update `config/default.yml` with the found executable path
+- Optionally run a basic test suite to validate the setup
+
+Run non-interactively from the project root (PowerShell):
+
+```powershell
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\installers\windows_installer.ps1 -Yes
+```
+
+To force recreation of the `.venv`, add the `-ForceVenv` switch:
+
+```powershell
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\installers\windows_installer.ps1 -Yes -ForceVenv
+```
+
+Installer logs are written to `tools/installer_windows.log` and status JSON to `tools/installer_windows_status.json`.
+
+### Manual (cross-platform)
+
+1. Create and activate a virtual environment in the project root:
+
+```bash
+python -m venv .venv
+# On Linux/macOS
+source .venv/bin/activate
+# On Windows (PowerShell)
+.venv\Scripts\Activate.ps1
+```
+
+2. Install dependencies:
+
+```bash
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+3. (Optional) Install the package in editable mode for development:
+
+```bash
+pip install -e .
+```
+
+## First steps and installation checks
+
+- Verify the virtual environment exists and `python` resolves to `.venv`'s interpreter.
+- Basic check: run the web GUI locally (see Usage below).
+- Use `pyplecs-setup` CLI (installed via `pyproject.toml` entry points) for convenience commands:
+
+```bash
+python -m pyplecs.cli.installer create-config
+python -m pyplecs.cli.installer check-windows
+```
+
+## Usage
+
+### Start the Web GUI
+
+The lightweight starter script is `start_webgui.py` at the project root. Run it from the project root (with the `.venv` active):
+
+```bash
+python start_webgui.py
+```
+
+Default server address: http://127.0.0.1:8001
+
+Available pages:
+
+- `/` - Dashboard
+- `/simulations` - Simulation manager
+- `/cache` - Cache monitor
+- `/settings` - Configuration (PLECS paths, orchestration settings)
+
+### CLI
+
+- `pyplecs-setup` (entry point) provides helper tasks such as creating a minimal `config/default.yml` and running platform checks.
+
+## Configuration
+
+The primary configuration file is `config/default.yml`. The Windows installer can populate the `plecs.executable_paths` entry. Example minimal config written by the installer:
+
+```yaml
+plecs:
+	executable_paths:
+		- 'C:\\Program Files\\Plexim\\PLECS 4.7 (64 bit)\\plecs.exe'
+```
+
+Other application settings are stored centrally and loaded via `pyplecs.config`.
+
+## Running tests
+
+The project includes pytest tests under `tests/`. Run the full test suite with the venv Python:
+
+```bash
+.venv\Scripts\Activate.ps1  # Windows PowerShell
+python -m pytest -q
+```
+
+For a quick installation validation without GUI dependencies, run the smoke test:
+
+```bash
+python -m pytest tests/test_smoke.py -v
+```
+
+The Windows installer offers an option to run `pytest tests/test_basic.py` to validate integration.
+
+## Troubleshooting
+
+### PLECS Path Configuration
+
+If you get a **PLECS executable not found** error, update the path in `config/default.yml`:
+
+```yaml
+plecs:
+  executable_paths:
+    - "C:/Program Files/Plexim/PLECS 4.7 (64 bit)/plecs.exe"  # Update to your version
+```
+
+You can add multiple paths for different PLECS versions:
+```yaml
+plecs:
+  executable_paths:
+    - "D:/OneDrive/Documenti/Plexim/PLECS 4.7 (64 bit)/plecs.exe"
+    - "C:/Program Files/Plexim/PLECS 4.7 (64 bit)/plecs.exe"
+    - "C:/Program Files/Plexim/PLECS 4.6 (64 bit)/plecs.exe"
+```
+
+### Installation Issues
+
+- `.venv` not present: ensure the installer was run from the project root. The installer will create `.venv` in the repository root. Use `-ForceVenv` to recreate.
+- Missing Python packages (ImportError): activate the venv and run `pip install -r requirements.txt`.
+- Installer logs: `tools/installer_windows.log` and `tools/installer_windows_status.json` contain detailed outcomes and error codes.
+
+Common error codes (written in status JSON):
+
+- `venv_creation_failed` / `venv_creation_exception` - venv creation failed
+- `pip_install_failed` / `pip_install_exception` - dependency installation failed
+- `plecs_path_invalid` - supplied PLECS path could not be found
+
+If you need interactive help on Windows, run the PowerShell installer without `-Yes` to use prompts.
+
+## Contributing
+
+Contributions welcome. Please open issues or pull requests. Follow these guidelines:
+
+- Run tests before pushing changes: `python -m pytest`
+- Keep code style with `black` and `flake8` as configured in `requirements.txt`
+- Update `docs/PROGRESS_MEMO.md` with high-level progress notes for large changes
+
+## License
+
+This project is licensed under the terms in the `LICENSE` file.
+
+---
+
+If you want, I can also generate a short Quick Start section with example commands tailored to Windows or Linux — tell me which platform you'd like prioritized.
 
 
----------------