Ai/PCSE_IRRIGATION_FERTILIZATION_GUIDE.md

راهنمای کامل PCSE در این پروژه

این سند توضیح می‌دهد PCSE در این پروژه دقیقا چه نقشی دارد، چگونه داده‌ها را مصرف می‌کند، خروجی آن چگونه ساخته می‌شود، و این خروجی چه اثری روی توصیه‌های آبیاری و کودهی دارد. تمرکز اصلی این راهنما روی اتصال بین این فایل‌ها است:

• crop_simulation/services.py
• crop_simulation/recommendation_optimizer.py
• crop_simulation/apps.py
• irrigation/apps.py
• fertilization/apps.py
• rag/services/irrigation.py
• rag/services/fertilization.py

---

1) PCSE چیست؟

PCSE مخفف Python Crop Simulation Environment است. این کتابخانه یک چارچوب شبیه‌سازی زراعی است که می‌تواند با مدل‌هایی مثل WOFOST رشد گیاه، توسعه فنولوژیک، تولید زیست‌توده، عملکرد، و پاسخ به آب و نیتروژن را شبیه‌سازی کند.

در این پروژه، PCSE نقش این‌ها را بر عهده دارد:

• تبدیل داده‌های مزرعه، هوا، خاک و برنامه مدیریت به یک اجرای شبیه‌سازی
• برآورد خروجی‌های کلیدی مثل:
  • yield_estimate
  • biomass
  • max_lai
• مقایسه سناریوهای مختلف آبیاری و کودهی
• تولید یک مبنای عددی برای recommendation engine

به زبان ساده:

• RAG متن توصیه را خوش‌بیان و کاربرپسند می‌کند
• PCSE منطق عددی و شبیه‌سازی سناریویی را تامین می‌کند

---

2) معماری کلی PCSE در این پروژه

جریان اصلی به این صورت است:

1. داده مزرعه از دیتابیس خوانده می‌شود
2. داده هوا از forecastها به فرمت قابل فهم برای PCSE تبدیل می‌شود
3. داده خاک و وضعیت سایت ساخته می‌شود
4. پروفایل گیاه و agromanagement آماده می‌شود
5. اگر recommendation آبیاری یا کودهی وجود داشته باشد، به TimedEvents تزریق می‌شود
6. مدل PCSE اجرا می‌شود
7. خروجی‌های روزانه، خلاصه و نهایی جمع می‌شوند
8. از روی آن‌ها شاخص عملکرد و recommendation سناریویی ساخته می‌شود
9. RAG از این خروجی به‌عنوان context_text استفاده می‌کند تا متن نهایی توصیه را بسازد

---

3) نقطه ورود اصلی PCSE

crop_simulation/apps.py

در crop_simulation/apps.py یک optimizer سراسری lazy-loaded تعریف شده:

• recommendation_optimizer
• get_recommendation_optimizer()

این optimizer از کلاس SimulationRecommendationOptimizer در crop_simulation/recommendation_optimizer.py ساخته می‌شود.

بنابراین:

• rag/services/irrigation.py از apps.get_app_config("crop_simulation").get_recommendation_optimizer() استفاده می‌کند
• rag/services/fertilization.py هم همین کار را انجام می‌دهد

یعنی هر دو سرویس recommendation در نهایت به موتور شبیه‌سازی crop_simulation وصل هستند.

---

4) نقش irrigation/apps.py

فایل irrigation/apps.py فقط یک AppConfig ساده نیست؛ در عمل تنظیمات پایه optimizer آبیاری را نگه می‌دارد.

پارامترهای مهم

simulation_model

مدل پیش‌فرض:

"Wofost81_NWLP_CWB_CNB"

این یعنی recommendationهای آبیاری قرار است روی مدلی ساخته شوند که هم water-limited و هم nutrient-aware است.

validity_days

3

توصیه آبیاری کوتاه‌مدت است و بیشتر به forecastهای نزدیک متکی است.

minimum_event_mm

4.0

هر نوبت آبیاری نباید از این کمتر شود، چون در عمل آبیاری‌های خیلی کوچک یا بی‌اثرند یا اجرای میدانی ضعیفی دارند.

significant_rain_threshold_mm

4.0

اگر بارش موثر به این آستانه برسد، recommendation می‌تواند محافظه‌کارتر شود یا پنجره اعتبار کوتاه‌تر شود.

stage_targets

برای هر مرحله رشد یک هدف رطوبت خاک تعریف شده:

• initial: 65%
• vegetative: 70%
• flowering: 75%
• fruiting: 68%

این‌ها مستقیما بر moisture_target_percent در توصیه نهایی اثر می‌گذارند.

strategy_profiles

سه استراتژی اصلی برای آبیاری تعریف شده:

• conservative
• balanced
• protective

هر استراتژی این مولفه‌ها را دارد:

• multiplier
• frequency_factor
• event_count

این‌ها تعیین می‌کنند:

• جمع کل آب بیشتر یا کمتر شود
• تعداد نوبت‌ها بیشتر یا کمتر شود
• توزیع آب در طول بازه forecast چگونه باشد

---

5) نقش fertilization/apps.py

این فایل هم مثل نسخه آبیاری، تنظیمات پایه recommendation optimizer کودهی را نگه می‌دارد.

پارامترهای مهم

simulation_model

باز هم مدل:

"Wofost81_NWLP_CWB_CNB"

یعنی recommendation کودهی بر مبنای مدلی ساخته می‌شود که نیتروژن را در سطح شبیه‌سازی لحاظ می‌کند.

validity_days

7

پنجره اعتبار کودهی بلندتر از آبیاری است، چون تصمیم تغذیه‌ای معمولاً کندتر و با اثر تجمعی‌تر است.

rain_delay_threshold_mm

3.0

اگر بارش موثر نزدیک باشد، برخی روش‌های مصرف یا زمان مصرف می‌توانند نامناسب شوند.

stage_targets

برای هر مرحله رشد، هدف تغذیه‌ای جداگانه تعریف شده است:

• n
• p
• k
• formula
• application_method
• timing

مثلا در مرحله flowering:

• نیاز پتاس بالاتر می‌شود
• فرمول 15-10-30 پیشنهاد می‌شود
• روش مصرف و timing هم متناسب با حساسیت گیاه تعیین می‌شود

strategy_profiles

سه استراتژی اصلی:

• maintenance
• balanced
• corrective

هر کدام ضریب مصرف و تمرکز متفاوت دارند. این استراتژی‌ها پایه سناریوسازی برای شبیه‌سازی یا heuristic هستند.

---

6) PCSE در crop_simulation/services.py چگونه کار می‌کند؟

6.1 نرمال‌سازی ورودی‌ها

قبل از اجرای مدل، ورودی‌ها یکنواخت می‌شوند:

• _normalize_weather_records()
• _normalize_agromanagement()
• _normalize_site_parameters_for_model()

6.2 ساخت payload مزرعه

تابع build_simulation_payload_from_farm() اطلاعات زیر را می‌سازد:

• weather
• soil
• site_parameters
• crop_parameters
• agromanagement

منابع آن:

• SensorData
• WeatherForecast
• پروفایل گیاه
• داده لایه خاک

6.3 ساخت داده خاک و سایت

در این مرحله مقادیر مهمی مثل این‌ها ساخته می‌شوند:

• SMFCF
• SMW
• RDMSOL
• WAV
• NAVAILI
• P_STATUS
• K_STATUS
• SOIL_PH
• EC

تعبیر عملی این مقادیر:

• WAV: آب در دسترس اولیه
• NAVAILI: نیتروژن اولیه در دسترس
• P_STATUS و K_STATUS: شاخص‌های وضعیت فسفر و پتاسیم
• SOIL_PH و EC: شرایط شیمیایی که روی کارایی تغذیه و رشد اثر دارند

6.4 لود کردن bindingهای PCSE

تابع _load_pcse_bindings() این اجزا را از package pcse می‌گیرد:

• ParameterProvider
• WeatherDataProvider
• WeatherDataContainer
• pcse.models

اگر package نصب نباشد، اجرای سناریوی واقعی PCSE ممکن نیست.

6.5 اجرای مدل

کلاس PcseSimulationManager قلب اجرای شبیه‌سازی است.

متد run_simulation() این کارها را انجام می‌دهد:

1. ساخت PreparedSimulationInput
2. normalize کردن weather / soil / crop / site / agromanagement
3. اجرای _run_with_pcse()
4. در مدل‌های Wofost81_NWLP اعمال adjustment برای P و K

6.6 خروجی‌های اصلی مدل

بعد از اجرا، این سه نوع خروجی جمع می‌شوند:

• daily_output
• summary_output
• terminal_output

و در نهایت metrics اصلی ساخته می‌شود:

• yield_estimate
• biomass
• max_lai

---

7) eventهای recommendation چگونه وارد شبیه‌سازی می‌شوند؟

این مهم‌ترین بخش اتصال PCSE به recommendationها است.

_parse_recommendation_events()

این تابع recommendation خام را به event قابل الحاق تبدیل می‌کند.

برای آبیاری:

• event_signal = "irrigate"
• کلید مقدار می‌تواند amount یا irrigation_amount باشد

برای کودهی:

• event_signal = "apply_n"
• کلید مقدار می‌تواند N_amount یا amount باشد

_merge_management_recommendations()

این تابع recommendationها را داخل TimedEvents همان campaign اصلی قرار می‌دهد.

پس وقتی شما یک recommendation جدید می‌دهید، در عمل:

• یک برنامه مدیریت جدید ساخته نمی‌شود
• همان agromanagement پایه مزرعه گرفته می‌شود
• eventهای جدید به آن تزریق می‌شوند

این طراحی مهم است چون:

• تقویم اصلی کشت حفظ می‌شود
• فقط تصمیم‌های مدیریتی جدید روی سناریو سوار می‌شوند

---

8) recommendation optimizer دقیقا چه می‌کند؟

فایل crop_simulation/recommendation_optimizer.py لایه تصمیم‌گیری سناریویی است.

کلاس اصلی:

• SimulationRecommendationOptimizer

این کلاس دو مسیر دارد:

• مسیر مبتنی بر PCSE
• مسیر heuristic fallback

اگر داده کافی و پروفایل simulation گیاه موجود باشد، اول تلاش می‌کند از PCSE استفاده کند. اگر نشد، به heuristic برمی‌گردد.

---

9) تاثیر PCSE روی توصیه آبیاری

9.1 ورودی‌های optimizer آبیاری

متد:

• optimize_irrigation()

ورودی‌ها:

• sensor
• plant
• forecasts
• daily_water_needs
• growth_stage
• irrigation_method

9.2 وقتی مسیر PCSE فعال می‌شود

اگر برای گیاه simulation profile معتبر وجود داشته باشد، متد _optimize_irrigation_with_pcse() اجرا می‌شود.

در این مسیر:

1. تنظیمات از irrigation/apps.py خوانده می‌شود
2. soil/site از سنسور و عمق خاک ساخته می‌شود
3. forecastها به weather record تبدیل می‌شوند
4. از روی strategy_profiles چند سناریوی آبیاری ساخته می‌شود
5. برای هر سناریو، eventهای irrigate به agromanagement تزریق می‌شود
6. هر سناریو با run_single_simulation() اجرا می‌شود
7. از روی yield_estimate هر سناریو، score ساخته می‌شود
8. بهترین سناریو انتخاب می‌شود

9.3 PCSE دقیقا چه چیزی را تغییر می‌دهد؟

PCSE باعث می‌شود recommendation آبیاری فقط بر پایه ET یا بارش نباشد. بلکه تاثیر برنامه آبیاری روی شاخص عملکرد گیاه هم دیده شود.

یعنی سیستم فقط نمی‌گوید:

• امروز 8 میلی‌متر آب بده

بلکه عملاً سناریوها را مقایسه می‌کند:

• اگر آب کمتر بدهیم، عملکرد چقدر افت می‌کند؟
• اگر آب را در نوبت‌های بیشتری پخش کنیم، نتیجه بهتر می‌شود؟
• اگر آبیاری حمایتی بدهیم، نسبت آب به عملکرد چطور تغییر می‌کند؟

9.4 خروجی نهایی آبیاری

خروجی recommendation آبیاری شامل این فیلدهاست:

• total_irrigation_mm
• amount_per_event_mm
• events
• event_dates
• timing
• moisture_target_percent
• validity_period
• reasoning

9.5 اثر مستقیم irrigation/apps.py

مقادیر این فایل مستقیم روی recommendation اثر دارند:

• stage_targets هدف رطوبت خاک را تعیین می‌کند
• strategy_profiles candidate scenarioها را تعریف می‌کند
• validity_days متن و پنجره اعتبار را تعیین می‌کند
• minimum_event_mm جلوی recommendationهای غیرعملی را می‌گیرد
• significant_rain_threshold_mm روی logic بارش موثر اثر دارد

9.6 اگر PCSE در دسترس نباشد

مسیر _optimize_irrigation_with_heuristic() استفاده می‌شود.

در این مسیر امتیازدهی بر اساس این‌هاست:

• نیاز آبی forecast
• بارش موثر
• رطوبت فعلی خاک
• دمای بالا
• باد
• بازده روش آبیاری

اما در این حالت شبیه‌سازی واقعی عملکرد انجام نمی‌شود. پس recommendation سبک‌تر و تخمینی‌تر است.

---

10) تاثیر PCSE روی توصیه کودهی

10.1 ورودی‌های optimizer کودهی

متد:

• optimize_fertilization()

ورودی‌ها:

• sensor
• plant
• forecasts
• growth_stage

10.2 مسیر PCSE برای کودهی

اگر simulation profile و forecast موجود باشد، _optimize_fertilization_with_pcse() اجرا می‌شود.

در این مسیر:

1. تنظیمات از fertilization/apps.py خوانده می‌شود
2. stage target مرحله رشد تعیین می‌شود
3. برای هر strategy profile یک دوز نیتروژن متفاوت ساخته می‌شود
4. event apply_n روی TimedEvents قرار می‌گیرد
5. هر سناریوی کودهی با PCSE اجرا می‌شود
6. yield_estimate سناریوها مقایسه می‌شود
7. بهترین استراتژی انتخاب می‌شود

10.3 PCSE دقیقا چه کمکی می‌کند؟

PCSE باعث می‌شود recommendation کودهی فقط بر اساس کمبود لحظه‌ای عناصر نباشد، بلکه اثر احتمالی سناریوی مصرف روی خروجی گیاه هم دیده شود.

یعنی سیستم فقط نمی‌گوید:

• چون نیتروژن پایین است، فلان مقدار کود بده

بلکه مقایسه می‌کند:

• اگر سناریوی نگهدارنده اجرا شود، عملکرد چقدر می‌شود؟
• اگر سناریوی اصلاحی اجرا شود، gain عملکردی چقدر است؟
• آیا افزایش دوز واقعاً ارزش دارد یا خیر؟

10.4 اثر fertilization/apps.py

مقادیر این فایل مستقیما بر recommendation اثر دارند:

• stage_targets دوز هدف N/P/K را تعیین می‌کند
• formula نوع کود پیشنهادی را تعیین می‌کند
• application_method روش مصرف را تعیین می‌کند
• timing زمان مناسب مصرف را تعیین می‌کند
• strategy_profiles سناریوهای رقابتی را می‌سازد
• rain_delay_threshold_mm روی ریسک زمان‌بندی مصرف اثر دارد
• validity_days پنجره اعتبار را تعیین می‌کند

10.5 heuristic fallback در کودهی

اگر PCSE اجرا نشود، _optimize_fertilization_with_heuristic() استفاده می‌شود.

این مسیر بر این مبنا تصمیم می‌گیرد:

• نیتروژن فعلی
• فسفر فعلی
• پتاسیم فعلی
• pH خاک
• مرحله رشد
• بارش پیش‌رو

خروجی آن هنوز ساختاریافته و مفید است، اما مثل مسیر PCSE مقایسه عملکرد شبیه‌سازی‌شده ندارد.

---

11) نقش P و K در حالی که event کودهی فقط apply_n است

در نسخه فعلی شبیه‌سازی، event مستقیم کودهی که وارد TimedEvents می‌شود بیشتر روی N_amount تمرکز دارد.

اما پروژه برای P و K هم یک adjustment تکمیلی دارد:

• _estimate_pk_stress_factor()
• _apply_pk_adjustment()

این بخش بعد از اجرای PCSE روی خروجی اعمال می‌شود.

منطق آن:

• اگر فسفر پایین باشد، p_factor کاهش می‌یابد
• اگر پتاسیم پایین باشد، k_factor کاهش می‌یابد
• اگر pH یا EC نامناسب باشد، penalty اعمال می‌شود
• سپس این factor روی:
  • yield_estimate
  • biomass
  • max_lai اعمال می‌شود

پس حتی اگر event سناریویی مستقیم بیشتر نیتروژنی باشد، وضعیت P, K, pH, EC باز هم روی recommendation نهایی اثر می‌گذارد.

---

12) RAG چطور از خروجی PCSE استفاده می‌کند؟

در rag/services/irrigation.py

این سرویس:

1. forecastها و داده مزرعه را می‌گیرد
2. نیاز آبی روزانه را از FAO-56 محاسبه می‌کند
3. optimizer شبیه‌سازی را صدا می‌زند
4. اگر optimized_result موجود باشد، context_text آن را به prompt اضافه می‌کند
5. LLM پاسخ را تولید می‌کند
6. پاسخ با fallback ساختاریافته merge می‌شود

نکته مهم:

• LLM مرجع عددی اصلی نیست
• optimized_result مرجع اصلی اعداد است

این موضوع حتی در prompt پیش‌فرض هم صریح آمده است.

در rag/services/fertilization.py

منطق مشابه است:

1. sensor و forecast خوانده می‌شود
2. optimizer کودهی اجرا می‌شود
3. context_text به system prompt اضافه می‌شود
4. LLM متن recommendation را می‌سازد
5. خروجی با fallback عددی merge می‌شود

در نتیجه:

• PCSE و optimizer عددها را می‌سازند
• RAG متن را کاربرپسند و اجرایی می‌کند

---

13) تفاوت بین simulation engine و recommendation layer

لایه simulation

در crop_simulation/services.py:

• سناریو اجرا می‌شود
• eventها merge می‌شوند
• خروجی‌های عملکردی تولید می‌شوند

لایه recommendation

در crop_simulation/recommendation_optimizer.py:

• چند سناریو candidate ساخته می‌شود
• همه با simulation یا heuristic ارزیابی می‌شوند
• بهترین گزینه انتخاب می‌شود
• context_text برای RAG تولید می‌شود

لایه presentation

در rag/services/irrigation.py و rag/services/fertilization.py:

• متن نهایی
• هشدارها
• list itemها
• توضیح توسعه‌پذیر

ساخته می‌شود.

---

14) سناریوی واقعی آبیاری در این پروژه

یک نمونه ساده:

1. forecast هفت روز آینده دریافت می‌شود
2. نیاز آبی روزانه محاسبه می‌شود
3. optimizer سه سناریوی آبیاری می‌سازد:
   • محافظه‌کارانه
   • متعادل
   • حمایتی
4. هر سناریو به TimedEvents تزریق می‌شود
5. PCSE برای هر سناریو اجرا می‌شود
6. عملکرد نسبی هر سناریو اندازه‌گیری می‌شود
7. بهترین سناریو انتخاب می‌شود
8. RAG همان سناریو را به زبان قابل فهم برای کاربر توضیح می‌دهد

---

15) سناریوی واقعی کودهی در این پروژه

یک نمونه ساده:

1. مرحله رشد تشخیص داده می‌شود
2. target غذایی همان مرحله از fertilization/apps.py خوانده می‌شود
3. چند سناریوی دوز و شدت مصرف ساخته می‌شود
4. برای هر سناریو event apply_n ساخته می‌شود
5. PCSE سناریوها را اجرا می‌کند
6. خروجی عملکرد مقایسه می‌شود
7. بهترین برنامه انتخاب می‌شود
8. RAG آن را به صورت JSON ساختاریافته به کاربر برمی‌گرداند

---

16) مزیت‌های استفاده از PCSE در توصیه آبیاری و کودهی

• recommendationها فقط rule-based نیستند
• تصمیم‌ها بر پایه مقایسه سناریو هستند
• امکان اتصال داده واقعی مزرعه به مدل رشد وجود دارد
• مرحله رشد، هوا، خاک و مدیریت همزمان دیده می‌شوند
• recommendation خروجی قابل توضیح‌تری برای LLM تولید می‌کند

---

17) محدودیت‌های فعلی پیاده‌سازی

این پروژه عملی و مفید است، اما چند محدودیت مهم دارد:

• کیفیت recommendation وابسته به کیفیت simulation profile گیاه است
• اگر پروفایل simulation وجود نداشته باشد، سیستم به heuristic fallback می‌رود
• event کودهی در شبیه‌سازی فعلی بیشتر نیتروژن‌محور است
• P و K به شکل adjustment پس از اجرا اعمال می‌شوند، نه لزوما event-driven کامل
• forecastهای هوا کوتاه‌مدت‌اند؛ پس recommendationها مخصوص تصمیم‌گیری عملیاتی نزدیک هستند
• score برخی سناریوها از yield_estimate / 100 ساخته می‌شود و هنوز می‌تواند با calibration دقیق‌تر بهبود یابد

---

18) جمع‌بندی عملی

اگر بخواهیم نقش PCSE را در یک جمله خلاصه کنیم:

PCSE در این پروژه موتور سنجش اثر تصمیم‌های آبیاری و کودهی روی عملکرد احتمالی گیاه است.

و اگر بخواهیم نقش irrigation/apps.py و fertilization/apps.py را هم در یک جمله بگوییم:

این دو فایل policy و defaultهای تصمیم‌گیری را تعریف می‌کنند، و optimizer با استفاده از همان policyها سناریو می‌سازد و با PCSE ارزیابی می‌کند.

بنابراین خروجی نهایی recommendation حاصل ترکیب سه لایه است:

1. داده واقعی مزرعه و forecast
2. شبیه‌سازی سناریویی با PCSE
3. تولید پاسخ ساختاریافته و قابل فهم با RAG

---

19) فایل‌هایی که اگر بخواهید این سیستم را توسعه دهید باید اول ببینید

• crop_simulation/services.py
• crop_simulation/recommendation_optimizer.py
• crop_simulation/apps.py
• irrigation/apps.py
• fertilization/apps.py
• rag/services/irrigation.py
• rag/services/fertilization.py

اگر بخواهید behavior سیستم را تغییر دهید:

• برای تغییر policy آبیاری: irrigation/apps.py
• برای تغییر policy کودهی: fertilization/apps.py
• برای تغییر منطق ارزیابی سناریو: crop_simulation/recommendation_optimizer.py
• برای تغییر اجرای واقعی مدل: crop_simulation/services.py
• برای تغییر متن و ساختار پاسخ: rag/services/irrigation.py و rag/services/fertilization.py