Cotton2K Simulation Model

Cotton2K is a cotton simulation model specially adapted for irrigated cotton production in arid regions. It was originally written by Prof. Avishalom Marani and has been rewritten in Rust with Python bindings.

Features

• High-performance cotton growth simulation
• Native Rust implementation with Python bindings
• TOML/JSON configuration format
• CSV output format
• Cross-platform support

Usage

As a Rust Library

Add to your Cargo.toml:

[dependencies]
cotton2k = { git = "https://github.com/tcztzy/cotton2k" }

As a Python Package

Install from PyPI:

pip install cotton2k

Or install locally:

cd bindings/python
pip install .

Example usage:

import cotton2k as c2k

# Run simulation with profile file
c2k.run("path/to/profile.toml")

As a Worker Process (for GUI/Batch)

The local worker binary runs one simulation job per process and emits JSONL progress events.

cargo run --bin cotton2k-worker -- \
  run \
  --profile /path/to/profile.toml \
  --run-dir /path/to/runs/job-001 \
  --run-id job-001

Artifacts in run-dir:

• output.csv
• meta.json
• request.json
• input/profile.toml or input/profile.json

As a Batch Scheduler (parallel worker processes)

Prepare a jobs file (jobs.json):

[
  { "profile": "/path/to/case-a/profile.toml", "run_id": "case-a" },
  { "profile": "/path/to/case-b/profile.toml", "run_id": "case-b" }
]

Run in parallel (default max parallelism is min(4, physical_cpu_cores)):

cargo run --bin cotton2k-batch -- \
  run \
  --jobs /path/to/jobs.json \
  --runs-root /path/to/runs \
  --max-parallel 2

Requirements

• Rust 1.70+ (for Rust usage)
• Python 3.10+ (for Python bindings)
• No libclang/LLVM toolchain is required for Python wheel builds

Building

Build Rust library:

cargo build --release

Build worker binary:

cargo build --release --bin cotton2k-worker

Build batch binary:

cargo build --release --bin cotton2k-batch

Build and install Python bindings:

cd bindings/python
maturin develop --release

Run the pure-Rust regression check suite:

./scripts/regression_pure_rust.sh

Roadmap

• Complete Rust migration
• GUI interface
• Improved documentation
• SWAP model integration

License

This project is licensed under:

• AGPLv3+ for the Rust implementation
• Original Cotton2K by Marani remains under GPLv2+

Correction

I used to think this project could be licensed under MIT license, but finally I found that my translate-to-Rust implementation should also follow GPL, so I relicensed all code in Rust & Python under AGPLv3+.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.