# 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`.