161 lines
4.6 KiB
Markdown
161 lines
4.6 KiB
Markdown
# PISCAL
|
|
|
|
PISCAL is a Fortran-based photosynthesis calculation tool for analyzing leaf-level gas exchange data. It supports C3, C4, and CAM photosynthetic pathways and provides parameter optimization for photosynthesis models.
|
|
|
|
## Quick Start with Docker
|
|
|
|
### Build the Docker Image
|
|
|
|
**Windows (PowerShell):**
|
|
```powershell
|
|
.\build-docker.ps1
|
|
```
|
|
|
|
**Linux/Mac (Bash):**
|
|
```bash
|
|
./build-docker.sh
|
|
```
|
|
|
|
### Run the Container
|
|
|
|
```bash
|
|
# Start container
|
|
docker run -d -p 2222:22 --name piscal-server piscal:latest
|
|
|
|
# SSH into container
|
|
ssh -p 2222 piscaladmin@localhost
|
|
# Password: piscaladmin
|
|
```
|
|
|
|
### Full Docker Documentation
|
|
|
|
See [README-Docker.md](README-Docker.md) for complete Docker build and deployment documentation, including:
|
|
- Container configuration
|
|
- Security best practices
|
|
- Troubleshooting
|
|
- CI/CD integration examples
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
piscal/
|
|
├── Dockerfile # Multi-stage Docker build configuration
|
|
├── build-docker.ps1 # Build script (Windows/PowerShell)
|
|
├── build-docker.sh # Build script (Linux/Mac/Bash)
|
|
├── README-Docker.md # Comprehensive Docker documentation
|
|
│
|
|
├── leafres/ # Leaf response calculation modules
|
|
│ ├── testarea/ # Test area source files
|
|
│ └── testrun/ # Test run configuration and Makefile
|
|
│
|
|
├── dataassim/ # Data assimilation and optimization
|
|
│ └── math/ # Mathematical libraries
|
|
│ ├── optimization/ # Optimization algorithms
|
|
│ ├── othersupmath/ # Supporting mathematical functions
|
|
│ ├── algebra/ # Linear algebra routines
|
|
│ ├── specialfuncs/ # Special mathematical functions
|
|
│ └── nonlinsystems/ # Nonlinear system solvers
|
|
│
|
|
└── piscal-manager/ # Container management scripts
|
|
├── piscal_manager.sh # Job orchestration script
|
|
├── piscal_launcher.sh # Execution wrapper
|
|
├── subdir_year.sh # Output organization utility
|
|
├── piscal_launcher.cfg # Configuration (reference for non-Docker)
|
|
└── README.txt # Manager scripts documentation
|
|
```
|
|
|
|
## Building from Source (Non-Docker)
|
|
|
|
PISCAL is written in Fortran and requires:
|
|
- `gfortran` (GNU Fortran compiler)
|
|
- `make`
|
|
- `xutils-dev`
|
|
|
|
To build manually:
|
|
```bash
|
|
cd leafres/testrun
|
|
make clean
|
|
make
|
|
```
|
|
|
|
The compiled executable will be located at `leafres/testrun/piscal`.
|
|
|
|
## Photosynthetic Pathway Support
|
|
|
|
PISCAL supports three photosynthetic pathway types:
|
|
- **C3_photosynthesis_leafweb** - C3 pathway (default)
|
|
- **C4_photosynthesis_leafweb** - C4 pathway
|
|
- **CAM_photosynthesis_leafweb** - CAM pathway
|
|
|
|
Specify the pathway type in the `piscal.cfg` configuration file.
|
|
|
|
## Input and Output
|
|
|
|
### Input Files
|
|
Place leaf gas exchange data files (CSV format) in the `input/` directory. See `piscal-manager/README.txt` for input file format details.
|
|
|
|
### Output Structure
|
|
PISCAL generates organized output in the following structure:
|
|
```
|
|
output/
|
|
├── clninput/ # Cleaned input data
|
|
└── fitresult/ # Optimization results
|
|
├── touser/ # User-facing results
|
|
│ ├── cntrlbestparameters.csv
|
|
│ ├── errormessage
|
|
│ └── warningmessage
|
|
└── nottouser/ # Internal/storage results
|
|
```
|
|
|
|
## Usage with piscal-manager Scripts
|
|
|
|
The container includes management scripts for job orchestration:
|
|
|
|
```bash
|
|
# Start a job
|
|
./piscal_manager.sh -d /path/to/workdir -s -p C3_photosynthesis_leafweb
|
|
|
|
# Check job status
|
|
./piscal_manager.sh -d /path/to/workdir
|
|
|
|
# Cleanup completed job
|
|
./piscal_manager.sh -d /path/to/workdir -c
|
|
```
|
|
|
|
See `piscal-manager/README.txt` for detailed script usage.
|
|
|
|
## Version History
|
|
|
|
Images are automatically tagged with:
|
|
- `piscal:YYYYMMDD-gitsha` - Date and commit-based version
|
|
- `piscal:latest` - Latest build
|
|
- `piscal:dev` - Development alias
|
|
|
|
## Security Notes
|
|
|
|
**Default Credentials:**
|
|
- Username: `piscaladmin`
|
|
- Password: `piscaladmin`
|
|
|
|
**Important:** Always change the default password after deployment:
|
|
```bash
|
|
ssh -p 2222 piscaladmin@localhost
|
|
passwd piscaladmin
|
|
```
|
|
|
|
See [README-Docker.md](README-Docker.md) for comprehensive security best practices.
|
|
|
|
## License
|
|
|
|
[Add license information here]
|
|
|
|
## Contributing
|
|
|
|
[Add contribution guidelines here]
|
|
|
|
## Support
|
|
|
|
For Docker-related issues, see the troubleshooting section in [README-Docker.md](README-Docker.md).
|
|
|
|
For PISCAL algorithm or calculation issues, refer to `piscal-manager/README.txt`.
|