PV tool

Summary

• Quick Start Guide ⚡
• About The Project
• Requirements
• Installation
• Usage
• Project Structure
• Additional Documentation
• Troubleshooting
• Contact

About The Project

This project is a Streamlit frontend for the PV-tool - a comprehensive Python toolset for geotechnical analysis of soil samples.

PV-tool Integration

The app integrates with the PV-tool via PyPI package pv-tool-logic to provide:

• Import & Validation: Load and validate geotechnical data from PV-tool Excel templates
• C-Phi Analysis: Determine cohesion and friction angle parameters (Mohr-Coulomb)
• SHANSEP Analysis: Stress History And Normalized Soil Engineering Properties
• SU Analysis: Undrained shear strength tables and profiles

The PV-tool is now available as a PyPI package - no git submodules needed! See PV-tool Integration Documentation for detailed technical information.

Features

✅ Multi-page Streamlit interface
✅ Full PV-tool integration via PyPI package (pv-tool-logic) ✅ Session state management for data sharing
✅ Interactive visualizations with Plotly
✅ Export capabilities (Excel, PDF, CSV)
✅ Support for multiple analysis types and investigation groups

This repository hosts a development version at http://localhost:8501 when running.

Requirements

• Python 3.11
• Streamlit >= 1.39.0
• pandas >= 2.0.0
• numpy >= 1.24.0
• plotly >= 5.18.0
• IDE for development - Visual Studio Code or PyCharm

Installation

1. Clone this repository

git clone https://github.com/your-username/pv-tool-app.git
cd pv-tool-app

2. Install dependencies

pip install -r requirements.txt

This will automatically install:

• Streamlit and all UI dependencies
• PV-tool-logic (PyPI package) - Core PV-tool functionality
• Data processing libraries (pandas, numpy, plotly)

Note: The PV-tool is now available as a PyPI package! No more git submodules needed.

• Visualization tools (plotly, kaleido)

4. Verify installation

Check if the PV-tool wrapper loads correctly:

python -c "from src.pv_tool_wrapper import pv_tool; print(f'PV-tool available: {pv_tool.available}')"

If you see PV-tool available: True, you're ready to go! 🎉

Run the app

streamlit run app.py

Or use the convenience scripts:

• Windows PowerShell: .\run.ps1
• Windows Command Prompt: run.bat

The app will open in your default browser at http://localhost:8501

Note: The Streamlit server must be running to access the app. If you navigate to http://localhost:8501 and see "This site can't be reached", you need to start the server first using one of the commands above.

Usage

Development Mode

For development, use the root app.py:

streamlit run app.py

Or use the convenience scripts:

• Windows PowerShell: .\run.ps1
• Windows Command Prompt: run.bat

Package/Production Mode

If you've installed the package via pip:

# Install the package
pip install pv_app

# Run the app anywhere
pv-app
# or
pv_app

The package commands automatically:

• ✅ Find and start the Streamlit app (uses internal streamlit_app.py)
• ✅ Open your browser automatically
• ✅ Use pre-configured settings (no prompts)
• ✅ Work from any directory

Note: There's only one source app.py file in the root directory. When building the package, it's automatically copied to pv_app/streamlit_app.py for distribution - no code duplication!

Automated Build Process

To build the package with automatic app.py synchronization:

PowerShell:

.\build.ps1

Command Prompt:

build.bat

These scripts automatically:

1. ✅ Copy app.py → pv_app/streamlit_app.py
2. ✅ Run poetry build --no-interaction
3. ✅ Show build results

Manual build (for advanced users):

# Copy app.py first
Copy-Item app.py pv_app\streamlit_app.py -Force
# Then build
poetry build --no-interaction

GitHub Actions (Automated CI/CD)

The repository includes automated workflows that trigger on push to GitHub:

🔄 App Sync Workflow (.github/workflows/sync-app.yml)

• Triggers: When app.py is modified and pushed
• Action: Automatically copies app.py → pv_app/streamlit_app.py
• Result: Package always stays in sync with your changes

🧪 Test Workflow (.github/workflows/test.yml)

• Triggers: Every push and pull request
• Actions:
  • Tests Python syntax validation
  • Checks imports and package structure
  • Builds and validates the package
  • Verifies streamlit_app.py is included

🚀 Build & Release Workflow (.github/workflows/build-release.yml)

• Triggers: Version tags (v1.0.0) or manual dispatch
• Actions:
  • Builds the package with Poetry
  • Creates GitHub releases with wheel files
  • Archives build artifacts

Usage: Just push your changes - GitHub handles the rest automatically! 🎉

Quick Start

1. Start the server (first time or after reboot):

   streamlit run app.py
   

   Or double-click run.bat or run.ps1

2. Access the app in your browser at http://localhost:8501

3. Stop the server when done: Press Ctrl+C in the terminal

Important: The server needs to be running for the app to be accessible. Think of it like starting a web server - you can't visit a website if the server isn't running!

Available Pages

Once the app runs, you can access the following pages:

1. Home - Landing page with overview of available analyses
2. 📥 Import en Validate - Import and validate geotechnical data from various formats (CSV, Excel, GEF, XML)
3. 📊 C-Phi analyse - Analyze cohesion and friction angle parameters using Mohr-Coulomb failure envelope
4. 🔬 SHANSEP analyse - Stress History And Normalized Soil Engineering Properties analysis
5. 📈 SU-analyse - Undrained shear strength analysis and interpretation

Navigation

• Use the sidebar to navigate between different analysis pages
• Each page includes demo data functionality for testing
• Data flows between pages using Streamlit's session state
• Start with "Import en Validate" to load your data, then proceed to specific analyses

Project Structure

pv-tool-app/
├── app.py                          # Main landing page
├── pages/                          # Streamlit multipage structure
│   ├── 1_📥_Import_en_Validate.py  # Data import and validation
│   ├── 2_📊_C-Phi_Analyse.py       # C-Phi analysis
│   ├── 3_🔬_SHANSEP_Analyse.py     # SHANSEP analysis
│   └── 4_📈_SU-Analyse.py          # SU analysis
├── requirements.txt                # Python dependencies
├── docs/                           # Documentation
├── src/                            # Source code (future)
├── static/                         # Static assets
└── test/                           # Tests

Additional Documentation

See the docs/ folder for additional documentation:

• PV-tool Integration - Technical details about PV-tool integration
• Getting Started - Detailed getting started guide
• Why Run Server - Explanation of Streamlit server requirement
• Quick Start - Quick reference card

PV-tool Resources

• PV-tool GitHub Repository
• PV-tool Documentation
• STOWA Proevenverzameling
• Analysis methodologies
• Data format specifications

Troubleshooting

Submodule Issues

If the PV-tool submodule is not properly loaded:

git submodule update --init --recursive

Missing Dependencies

If you encounter import errors:

pip install -r requirements.txt --upgrade

Import Errors

Make sure you're running Python 3.11 and all dependencies are installed:

python --version
pip list

Contact

Product owner: Tjalda Deenekamp