Xây dựng lịch kiểm tra tưới cây trong nhà từ danh sách các loại cây cùng kích thước và chất liệu chậu, điều kiện ánh sáng, khả năng thoát nước và ngày tưới gần nhất. Điều chỉnh từng khoảng thời gian chờ theo loại chậu, ánh sáng, độ ẩm và mùa (theo bán cầu, giãn cách dài hơn vào mùa đông), sắp xếp lịch kiểm tra vào các ngày cố định trong tuần đã chọn, giải thích rõ thế nào là 'cần tưới nước' và lượng nước cần tưới bao nhiêu, đồng thời cảnh báo các rủi ro như chậu không có lỗ thoát nước. Bao gồm bộ lập lịch bằng Python sử dụng thư viện chuẩn (stdlib) có tính năng xuất tệp .ics và --self-test.
---
name: houseplant-watering-schedule-planner
description: Xây dựng lịch kiểm tra tưới cây trong nhà từ danh sách các loại cây cùng kích thước và chất liệu chậu, điều kiện ánh sáng, khả năng thoát nước và ngày tưới gần nhất. Điều chỉnh từng khoảng thời gian chờ theo loại chậu, ánh sáng, độ ẩm và mùa (theo bán cầu, giãn cách dài hơn vào mùa đông), sắp xếp lịch kiểm tra vào các ngày cố định trong tuần đã chọn, giải thích rõ thế nào là 'cần tưới nước' và lượng nước cần tưới bao nhiêu, đồng thời cảnh báo các rủi ro như chậu không có lỗ thoát nước. Bao gồm bộ lập lịch bằng Python sử dụng thư viện chuẩn (stdlib) có tính năng xuất tệp .ics và --self-test.
---
# Công Cụ Lập Lịch Tưới Cây Trong Nhà
Bạn giúp mọi người giữ cho cây trồng trong nhà luôn tươi tốt mà không chỉ tưới máy móc theo lịch. Kế hoạch sẽ cho họ biết khi nào cần **kiểm tra** từng cây và cần quan sát dấu hiệu gì; họ chỉ tưới nước khi quy tắc riêng của cây đó báo đã đến lúc. Bạn điều chỉnh linh hoạt theo điều kiện thực tế (chậu cây, ánh sáng, hệ thống sưởi, mùa trong năm), giữ cho thói quen thật đơn giản (hai ngày kiểm tra cố định mỗi tuần nếu họ muốn), và chỉ ra những cách bố trí gây chết cây nhiều nhất: chậu không có lỗ thoát nước, cây mọng nước đặt ở góc tối, cây dương xỉ bị khô kiệt trong chậu đất nung (terracotta).
## Các tệp trong kỹ năng này
- `scripts/watering_planner.py` - đọc tệp CSV danh sách cây, gán cho mỗi cây một nhóm nhu cầu nước, tính toán khoảng thời gian giữa các lần kiểm tra theo mùa, tạo lịch trình (có tùy chọn khớp vào các ngày cố định trong tuần), ước tính lượng nước cho mỗi cây, gắn cờ cảnh báo các cách trồng rủi ro, và có thể xuất ra tệp .ics (chỉ dùng thư viện chuẩn của Python 3.8+)
- `references/plant-water-profiles.md` - sáu nhóm nhu cầu tưới nước, các loại cây phổ biến trong từng nhóm, cách kiểm tra "cần tưới nước" cũng như dấu hiệu tưới quá nhiều hoặc quá ít nước
- `references/adjustment-factors.md` - cách kích thước chậu, chất liệu chậu, ánh sáng, độ ẩm, mùa và khả năng thoát nước làm thay đổi khoảng cách giữa các lần kiểm tra, kèm theo các hệ số nhân mà kịch bản sử dụng và cách tinh chỉnh chúng sau vài tuần
- `templates/watering-plan.md` - bản kế hoạch dài một trang để gửi lại cho người dùng (lịch trình hàng tuần, bảng tóm tắt nhanh cho từng cây, các cảnh báo, ngày đánh giá lại)
- `examples/plants.csv` - mười chậu cây trong một căn hộ có bật sưởi vào thời điểm cuối tháng Mười
- `examples/plan-output.md` - kết quả đầu ra thực tế của bộ lập lịch cho danh sách cây đó
## Quy trình thực hiện
### 1. Thu thập danh sách cây trồng
Đối với mỗi cây: tên gọi, loại cây (tên loài hoặc mô tả kiểu "trông giống cây mọng nước"), đường kính chậu tính bằng cm, chất liệu chậu (nhựa, gốm tráng men, đất nung terracotta, vải trồng cây, chậu tự tưới), mức độ ánh sáng tại vị trí đặt cây (thấp = xa cửa sổ, trung bình, sáng = ánh sáng gián tiếp mạnh, trực tiếp = nắng chiếu thẳng lên lá hàng giờ liền), chậu có lỗ thoát nước hay không, và lần tưới nước gần nhất là khi nào. Hãy hỏi thêm về bán cầu nơi họ sống, căn nhà có đang bật sưởi hay không (không khí khô), và những ngày nào trong tuần thuận tiện cho việc kiểm tra nhanh. Nếu không rõ tên cây, hãy yêu cầu mô tả qua ảnh hoặc xếp tạm vào nhóm "top_dry" (khô lớp đất mặt) và nói rõ giả định đó.
### 2. Chạy bộ lập lịch
```
python3 scripts/watering_planner.py examples/plants.csv --start 2026-10-30 --weeks 6 --check-days Mon,Thu --humidity low
python3 scripts/watering_planner.py plants.csv --hemisphere south --weeks 8 --ics plants.ics
python3 scripts/watering_planner.py plants.csv --json
python3 scripts/watering_planner.py --self-test
```
Mã thoát 0 = đã tạo xong kế hoạch, 1 = đã tạo kế hoạch nhưng có cảnh báo mức HIGH cần xử lý ngay (ví dụ: không có lỗ thoát nước), 2 = dữ liệu đầu vào không hợp lệ (chất liệu hoặc mức ánh sáng không xác định, kích thước chậu tính bằng mm, định dạng ngày sai). Nếu không chạy mã, hãy tự tra bảng phân loại và tính theo các hệ số nhân trong tài liệu tham chiếu.
### 3. Kiểm tra kết quả trước khi bàn giao
- Mỗi cây đều có một khoảng cách kiểm tra ở thời điểm hiện tại và, nếu kế hoạch kéo dài sang mùa tiếp theo, khoảng cách mới tương ứng (ví dụ: "7 d (winter: 9 d)").
- Những loại cây ưa ẩm liên tục (dương xỉ, đuôi công calathea, lan ý, húng quế) có thể cần nhiều ngày kiểm tra hơn số ngày cố định trong lịch trình; bộ lập lịch sẽ chỉ rõ điều này. Hãy gợi ý thêm ngày kiểm tra thứ ba, đổi sang chậu nhựa, hoặc dùng chậu tự tưới riêng cho những cây này.
- "Overdue" (Quá hạn) có nghĩa là thời điểm tưới lần cuối cộng với khoảng cách kiểm tra đã trôi qua: hãy kiểm tra cây đó đầu tiên.
- Đọc kỹ các cảnh báo và đưa những cảnh báo mức HIGH thành hành động ưu tiên hàng đầu trong kế hoạch.
### 4. Bàn giao kết quả
Điền vào `templates/watering-plan.md`: lịch trình hàng tuần (kiểm tra cây nào vào ngày nào), bảng hướng dẫn nhanh cho từng cây kèm bài kiểm tra "tưới khi nào" và lượng nước cần tưới, các cảnh báo cùng hướng xử lý, và ngày xem xét lại sau 2-3 tuần để giãn ra hoặc rút ngắn khoảng cách kiểm tra dựa trên tình trạng thực tế họ ghi nhận được ở mỗi lần kiểm tra.
## Ví dụ kết quả
Mười chậu cây, bắt đầu từ Thứ Sáu ngày 2026-10-30, kéo dài sáu tuần, kiểm tra vào các ngày Thứ Hai và Thứ Năm, có bật lò sưởi (độ ẩm thấp). Dương xỉ, đuôi công calathea, lan ý và húng quế được kiểm tra vào mọi ngày kiểm tra trong tuần; trầu bà lá xẻ (monstera) khoảng mỗi tuần một lần (các ngày Thứ Năm); trầu bà (pothos) mỗi tuần một lần (các ngày Thứ Hai); lưỡi hổ mỗi 16 ngày, giãn ra thành 21 ngày vào tháng Mười Hai; cây kim tiền (ZZ plant) mỗi 20 ngày; xương rồng hiện tại mỗi 6 ngày, sang mùa đông là 9 ngày (cây này đang quá hạn, lần tưới cuối là 15 tháng Mười). Cây lan ý đang đặt trong chậu trang trí không có lỗ thoát nước (Cảnh báo HIGH: hãy trồng trong chậu nhựa ươm cây đặt lọt bên trong và đổ hết nước đọng ở chậu bọc ngoài sau khi tưới). Cây dương xỉ trồng trong chậu đất nung và cây húng quế cần được kiểm tra mỗi 1-2 ngày, nên lịch kiểm tra hai lần một tuần không đáp ứng đủ. Xem chi tiết tại `examples/plan-output.md`.
## Quy tắc
- Không bao giờ chỉ định tưới nước cứng nhắc theo lịch cố định mà không kiểm tra trước; luôn gắn mỗi lần kiểm tra với bài thử "tưới khi nào" của từng loại cây.
- Tưới đẫm cho đến khi nước chảy ra ở đáy chậu, sau đó đổ bỏ nước thừa trong đĩa hứng sau 15 phút; tuyệt đối không để đáy chậu ngâm trong nước (với hoa lan: ngâm chậu rồi nhấc ra để ráo nước hoàn toàn).
- Vào mùa đông và ở nơi ánh sáng yếu, cây tiêu thụ ít nước hơn: hãy kéo dài khoảng cách giữa các lần tưới thay vì tưới nhấp nháp từng chút một.
- Khi thấy lá vàng đi kèm đất vẫn còn ướt, hãy xác định nguyên nhân là do tưới quá nhiều nước chứ không phải cây bị khát; phải nêu rõ điều này trước khi đề xuất tưới thêm nước.
- Không tự ý đoán loài cây từ một tên gọi mơ hồ; hãy hỏi lại người dùng hoặc nêu rõ nhóm nhu cầu nước mà bạn đã giả định.
- Chỉ đề cập đến vấn đề độc tính đối với thú cưng khi người dùng hỏi về độ an toàn hoặc có nhắc tới thú cưng/trẻ nhỏ; không thêm thắt thông tin lan man vào kế hoạch.
FILE:references/plant-water-profiles.md
# Các nhóm nhu cầu tưới nước
| Nhóm | Các loại cây điển hình | Tưới khi | Khoảng cách kiểm tra cơ sở* | Độ giãn cách vào mùa đông |
|---|---|---|---|---|
| succulent | xương rồng, nha đam (lô hội), sen đá (echeveria), cây ngọc bích (jade), móng rồng (haworthia), chuỗi ngọc (string of pearls) | đất khô hoàn toàn từ trên xuống đáy: cắm một chiếc đũa gỗ chạm đáy chậu khi rút ra thấy sạch và khô ráo; nhấc chậu thấy nhẹ hẳn | 10 ngày | x2.5 (nhiều loại xương rồng hầu như không cần tưới từ tháng 12 đến tháng 2) |
| dry_tolerant | lưỡi hổ (sansevieria), kim tiền (ZZ plant), cọ đuôi ngựa (ponytail palm), yucca, lan cẩm cù (hoya), peperomia | ít nhất 3/4 độ sâu của đất trong chậu đã khô | 12 ngày | x2.0 |
| top_dry | trầu bà (pothos), trầu bà lá xẻ (monstera), philodendron, đa búp đỏ (rubber plant), bàng Singapore (fiddle leaf fig), thiết mộc lan (dracaena), dây nhện (spider plant), kim ngân (money tree), vạn lộc/ngọc ngân (aglaonema), môn quan âm (alocasia), hồng môn (anthurium), cau tiểu trâm (parlor palm), thu hải đường (begonia), xương rồng Giáng sinh (Christmas cactus) | khô 1/3 lớp đất phía trên (thử bằng ngón tay ngập đến đốt thứ hai đối với chậu 15 cm) | 6 ngày | x1.6 |
| evenly_moist | dương xỉ Boston và dương xỉ tóc thần vệ nữ (maidenhair fern), đuôi công (calathea), maranta (prayer plant), lan ý (peace lily), lá may mắn (fittonia) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để đất khô hoàn toàn | 3 ngày | x1.3 |
| orchid | lan hồ điệp (phalaenopsis) trồng trong giá thể vỏ thông | rễ chuyển màu xám bạc (màu xanh lá = vẫn còn ướt) và vỏ thông đã khô; ngâm nước 10 phút, sau đó để ráo hoàn toàn | 7 ngày | x1.4 |
| herb | húng quế, bạc hà, mùi tây (parsley) đặt trên bệ cửa sổ | lớp đất mặt 1-2 cm đã khô | 2 ngày | x1.2 |
*Mức cơ sở = mùa xuân, chậu nhựa 15 cm có lỗ thoát nước, ánh sáng trung bình, độ ẩm bình thường. Mùa thu nằm ở mức giữa mùa xuân và mùa đông; mùa hè nhân với hệ số x0.85. Xem `adjustment-factors.md`.
## Cách kiểm tra độ ẩm (30 giây cho mỗi cây)
1. **Thử bằng ngón tay:** ấn ngón tay vào đất đến độ sâu theo quy tắc của nhóm cây. Đất khô và tơi rời = khô; mát và dính vào tay = còn ẩm.
2. **Ước lượng độ nặng:** hãy nhấc thử các chậu nhỏ ngay sau khi vừa tưới đẫm một lần để cảm nhận sự khác biệt giữa lúc chậu "no nước" và lúc "cạn nước".
3. **Dùng đũa gỗ/que tre:** đối với các chậu sâu lòng và cây mọng nước, hãy cắm một que xiên gỗ xuống tận đáy chậu trong một phút; nếu rút ra thấy que sẫm màu và ẩm nghĩa là chưa cần tưới.
4. **Bút đo độ ẩm đất** chỉ mang tính tham khảo tương đối; thiết bị này đo độ dẫn điện của muối khoáng lẫn nước nên thường báo sai khi cắm vào giá thể vỏ thông hoặc đất trộn nhiều cát.
## Các dấu hiệu nhận biết
| Tưới quá nhiều nước (phổ biến hơn) | Tưới thiếu nước |
|---|---|
| lá tầng dưới ngả vàng trong khi đất vẫn ướt, gốc thân mềm nhũn hoặc chuyển màu đen, rễ bị thối nhũn, xuất hiện ruồi nấm (fungus gnats), đất có mùi chua ủng | mép lá khô giòn chuyển màu nâu, lá rũ xuống nhưng tươi tỉnh lại chỉ sau vài giờ được tưới nước, đất co lại tách rời khỏi thành chậu, nhấc chậu thấy rất nhẹ |
| Cách khắc phục: ngừng tưới ngay, kiểm tra bộ rễ, thay sang giá thể đất khô mới nếu rễ đã bị thối, kéo dài khoảng cách giữa các lần kiểm tra | Cách khắc phục: tưới đẫm hoàn toàn (ngâm đáy chậu trong nước 20-30 phút nếu đất bị trơ không ngấm nước), rút ngắn khoảng cách kiểm tra lại một chút |
Cây bị rũ lá trong khi đất vẫn **ướt** có nghĩa là bộ rễ đã bị tổn thương: tuyệt đối không tưới thêm nước.
## Kỹ thuật tưới nước
- Tưới từ từ khắp bề mặt đất cho đến khi nước chảy ra ở lỗ đáy chậu; chờ một lát, sau đó đổ bỏ nước đọng trong đĩa hứng sau khoảng 15 phút.
- Dùng nước ở nhiệt độ phòng. Cây đuôi công (calathea) và một số loài dương xỉ dễ bị cháy nâu đầu lá nếu tưới bằng nước cứng hoặc nước đã làm mềm bằng muối; dùng nước mưa hoặc nước lọc sẽ tốt hơn.
- Tưới thẩm thấu ngược từ đáy (ngâm đáy chậu trong khay nước khoảng 20-30 phút) rất hiệu quả với các chậu nhỏ và đất bị khô co rút lại; thỉnh thoảng hãy tưới từ trên xuống để rửa trôi muối khoáng tích tụ.
- Chậu tự tưới: châm thêm nước vào bình chứa khi đã cạn và thỉnh thoảng cứ để bình chứa cạn khô trong một hoặc hai ngày để rễ cây được hô hấp; không dùng loại chậu này cho cây mọng nước.
FILE:references/adjustment-factors.md
# Các hệ số điều chỉnh
Khoảng cách kiểm tra = số ngày cơ sở (theo nhóm cây) x kích thước chậu x chất liệu chậu x ánh sáng x độ ẩm x mùa, được làm tròn và giới hạn trong khoảng 1..45 ngày. Dưới đây là các hệ số nhân được sử dụng trong `scripts/watering_planner.py`.
| Yếu tố | Giá trị | Hệ số nhân | Lý do |
|---|---|---|---|
| Đường kính chậu | dưới 10 cm | 0.6 | ít đất, khô chỉ sau vài ngày |
| | 10-13 cm | 0.8 | |
| | 14-19 cm | 1.0 | mức tham chiếu chuẩn |
| | 20-27 cm | 1.3 | nhiều đất hơn nên giữ nước lâu hơn |
| | từ 28 cm trở lên | 1.6 | chậu lớn vẫn còn ướt ở đáy rất lâu sau khi bề mặt đã khô: cần kiểm tra sâu xuống dưới |
| Chất liệu | nhựa, tráng men, gốm sứ, kim loại | 1.0 | thành chậu không thoát hơi nước |
| | đất nung (terracotta) / đất sét không tráng men | 0.75 | thành chậu thấm hút và làm bay hơi nước |
| | túi vải trồng cây (fabric grow bag) | 0.7 | khô nhanh từ mọi phía |
| | chậu tự tưới | 1.5 | bình chứa cấp ẩm dần cho đất; hãy kiểm tra bình chứa nước thay vì mặt đất |
| Ánh sáng | thấp (cách cửa sổ trên 2 m, phòng hướng Bắc) | 1.4 | cây ít phát triển, tiêu thụ ít nước |
| | trung bình | 1.0 | |
| | ánh sáng gián tiếp mạnh | 0.85 | |
| | nắng chiếu trực tiếp lên lá | 0.7 | |
| Độ ẩm | thấp (đang bật sưởi, dưới ~35 %) | 0.85 | đất và lá mất nước nhanh hơn |
| | bình thường | 1.0 | |
| | cao (phòng tắm, có máy tạo ẩm) | 1.15 | |
| Mùa | mùa xuân | 1.0 | |
| | mùa hè | 0.85 | |
| | mùa thu | mức giữa của mùa xuân và mùa đông | đà tăng trưởng chậm lại khi ngày ngắn đi |
| | mùa đông | hệ số giãn cách mùa đông theo từng nhóm cây (từ x1.2 đến x2.5) | |
Phân chia mùa: ở Bắc bán cầu, tháng 12-tháng 2 là mùa đông, tháng 3-tháng 5 là mùa xuân, tháng 6-tháng 8 là mùa hè, tháng 9-tháng 11 là mùa thu; ở Nam bán cầu lệch đi sáu tháng. Nếu đặt cây ngay cạnh lò sưởi hoặc trong phòng kính có sưởi ấm, hãy chọn mức độ ẩm "low" (thấp) ngay cả vào mùa đông.
## Khả năng thoát nước
Chậu không có lỗ thoát nước là nguyên nhân đơn lẻ lớn nhất gây thối rễ. Cách tốt nhất: giữ nguyên cây trong chậu nhựa ươm cây đặt lọt bên trong chậu trang trí và đổ hết nước đọng ở chậu ngoài sau khi tưới 15 phút. Nếu bắt buộc phải trồng trực tiếp trong chậu không có lỗ, chỉ tưới khoảng một nửa lượng nước thông thường và nghiêng nhẹ chậu để kiểm tra xem có nước đọng dưới đáy không. Bộ lập lịch sẽ gắn cờ trường hợp này ở mức cảnh báo HIGH.
## Lượng nước tưới
Khoảng 15-25 % thể tích chậu, tưới cho đến khi thấy nước thoát ra ở lỗ đáy. Bộ lập lịch ước tính thể tích chậu từ đường kính (giả định chậu thành đứng có chiều cao bằng khoảng 0.9 lần chiều rộng), vì vậy chậu 15 cm cần khoảng 450 ml nước, chậu 24 cm cần khoảng 1.75 lít. Cây mọng nước và cây chịu hạn cũng cần được tưới đẫm mỗi lần như vậy, chỉ là tần suất thưa hơn.
## Tinh chỉnh sau hai hoặc ba tuần
- Đất vẫn còn ẩm ở hầu hết các lần kiểm tra: hãy kéo dài khoảng cách kiểm tra của cây đó thêm 25-50 % (hoặc chuyển thông số ánh sáng sang "low" nếu cây đặt xa cửa sổ).
- Đất khô cong ở mọi lần kiểm tra và lá cây bị rũ xuống: rút ngắn khoảng cách kiểm tra đi 25 %.
- Hãy cập nhật trực tiếp các thay đổi này vào tệp CSV (ví dụ: đổi nhóm cây hoặc mức ánh sáng) rồi chạy lại công cụ, thay vì cố ghi nhớ các trường hợp ngoại lệ trong đầu.
- Chạy lại kế hoạch khi bắt đầu bật hoặc tắt hệ thống sưởi, khi bạn thay chậu mới (chậu lớn hơn = khoảng cách dài hơn), hoặc khi đổi vị trí đặt cây.
## Các trường hợp nằm ngoài quy tắc tính khoảng cách
- Cây mới thay chậu: tưới đẫm một lần ngay sau khi thay chậu, sau đó chờ đến khi đất đạt đúng điều kiện trong quy tắc mới tưới tiếp.
- Các loại củ ngủ đông và xương rồng trong giai đoạn nghỉ đông lạnh giá (5-12 C): hầu như không cần tưới nước; chỉ cần kiểm tra mỗi tháng một lần là đủ.
- Bón phân: chỉ thực hiện vào mùa xuân và mùa hè, pha loãng bằng một nửa liều lượng khuyến cáo, bón vào đúng ngày tưới nước.
FILE:templates/watering-plan.md
# Kế hoạch chăm sóc cây: <nhà / phòng>
**Giai đoạn:** <2026-10-30 đến 2026-12-10> **Ngày kiểm tra:** <Thứ Hai và Thứ Năm, 5-10 phút>
**Điều kiện:** <Bắc bán cầu, đang bật sưởi (không khí khô)> **Đánh giá lại vào:** <2026-11-16>
## Việc cần làm ngay
- <Lan ý (Peace lily): không có lỗ thoát nước - hãy chuyển cây sang chậu nhựa ươm đặt lọt bên trong chậu bọc ngoài; đổ bỏ nước đọng ở chậu bọc ngoài sau khi tưới 15 phút>
- <Spike (xương rồng): đã quá hạn - cần kiểm tra ngay vào Thứ Hai>
## Lịch trình hàng tuần
| Ngày | Kiểm tra các cây sau |
|---|---|
| <Thứ Hai> | <dương xỉ, đuôi công calathea, lan ý, húng quế, hoa lan, trầu bà pothos, xương rồng (mỗi Thứ Hai cách tuần trong tháng Mười Hai)> |
| <Thứ Năm> | <dương xỉ, đuôi công calathea, lan ý, húng quế, hoa lan, trầu bà lá xẻ monstera; lưỡi hổ mỗi 2-3 tuần> |
## Bảng hướng dẫn nhanh
| Cây | Tưới khi | Lượng nước ước tính | Ghi chú |
|---|---|---|---|
| <Monty (monstera)> | <khô 1/3 lớp đất mặt> | <~1.75 l cho đến khi thoát nước> | <cửa sổ hướng Đông nhiều sáng> |
| <Sansa (snake plant)> | <khô 3/4 độ sâu đất> | <~450 ml> | <Tháng Mười Hai: mỗi 3 tuần> |
## Cách kiểm tra
- Ấn ngón tay vào đất đến độ sâu ghi trong cột "Tưới khi"; chỉ tưới nếu đất đã khô đến độ sâu đó.
- Tưới cho đến khi nước chảy ra ở đáy chậu, đổ hết nước trong đĩa hứng sau 15 phút.
- Đất ướt + lá vàng = thừa nước: bỏ qua lượt tưới và báo lại cho tôi.
## Cảnh báo
- <Fernando (dương xỉ Boston) trồng trong chậu đất nung bị khô chỉ sau 2 ngày khi bật sưởi: hãy thêm một buổi kiểm tra vào Thứ Bảy hoặc chuyển sang chậu nhựa>
- <Húng quế cần được kiểm tra hàng ngày trên bệ cửa sổ đầy nắng; hãy tưới ngâm đáy chậu mỗi khi bạn đi ngang qua>
## Khi đánh giá lại
Đối với mỗi cây, hãy ghi chú xem đất thường vẫn còn ẩm (cần giãn cách dài hơn) hay đã khô kiệt (cần rút ngắn lại) vào các buổi kiểm tra; tôi sẽ cập nhật lại kế hoạch.
FILE:examples/plants.csv
name,plant,pot_cm,pot_material,light,drainage,last_watered,notes
Monty,monstera,24,plastic,bright,yes,2026-10-28,living room by the east window
Pothos shelf,pothos,14,glazed,medium,yes,2026-10-27,trailing from the bookshelf
Sansa,snake plant,17,terracotta,low,yes,2026-10-20,hallway corner
Zed,zz plant,20,plastic,medium,yes,,new from the shop
Fernando,boston fern,20,terracotta,bright,yes,2026-10-29,bathroom shelf
Cal,calathea,15,plastic,medium,yes,2026-10-28,bedroom
Spike,cactus,10,terracotta,direct,yes,2026-10-15,south windowsill
Peace lily,peace lily,18,glazed,low,no,2026-10-26,decorative pot with no hole
Orchid,phalaenopsis,12,plastic,bright,yes,2026-10-25,kitchen window
Basil,basil,13,terracotta,direct,yes,2026-10-29,kitchen windowsill
FILE:examples/plan-output.md
# Kế hoạch tưới cây trong nhà: 2026-10-30 đến 2026-12-10
Bán cầu: Bắc Mùa lúc bắt đầu: mùa thu Độ ẩm: thấp Ngày kiểm tra: Thứ Hai, Thứ Năm Số lượng cây: 10
Kiểm tra không đồng nghĩa với tưới nước: hãy chạm tay cảm nhận độ ẩm của đất và chỉ tưới khi quy tắc của cây báo đã đến lúc.
## Danh sách cây
| Cây | Nhóm | Chậu | Ánh sáng | Kiểm tra mỗi | Tưới khi | Lượng nước ước tính | Số lần kiểm tra |
|---|---|---|---|---|---|---|---|
| Monty (monstera) | top_dry | nhựa 24 cm | sáng | 7 d (winter: 9 d) | khô 1/3 lớp đất phía trên (khoảng 3-5 cm đối với chậu 15 cm) | ~1750 ml (cho đến khi thoát nước) | 6 |
| Pothos shelf (pothos) | top_dry | tráng men 14 cm | trung bình | 7 d (winter: 8 d) | khô 1/3 lớp đất phía trên (khoảng 3-5 cm đối với chậu 15 cm) | ~350 ml (cho đến khi thoát nước) | 6 |
| Sansa (snake plant) | dry_tolerant | đất nung 17 cm | thấp | 16 d (winter: 21 d) | đất khô ít nhất 3/4 độ sâu từ trên xuống | ~450 ml (cho đến khi thoát nước) | 3 |
| Zed (zz plant) | dry_tolerant | nhựa 20 cm | trung bình | 20 d | đất khô ít nhất 3/4 độ sâu từ trên xuống | ~750 ml (cho đến khi thoát nước) | 2 |
| Fernando (boston fern) | evenly_moist | đất nung 20 cm | sáng | 2 d (winter: 3 d) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để khô hoàn toàn | ~1000 ml (cho đến khi thoát nước) | 12 |
| Cal (calathea) | evenly_moist | nhựa 15 cm | trung bình | 3 d (winter: 3 d) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để khô hoàn toàn | ~450 ml (cho đến khi thoát nước) | 12 |
| Spike (cactus) (quá hạn: kiểm tra ngay ngày đầu tiên) | succulent | đất nung 10 cm | trực tiếp | 6 d (winter: 9 d) | đất khô hoàn toàn đến tận đáy (rút đũa gỗ ra thấy sạch và khô) | ~100 ml (cho đến khi thoát nước) | 6 |
| Peace lily (peace lily) | evenly_moist | tráng men 18 cm, KHÔNG lỗ | thấp | 4 d (winter: 5 d) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để khô hoàn toàn | ~375 ml, không tưới nhiều hơn | 12 |
| Orchid (phalaenopsis) | orchid | nhựa 12 cm | sáng | 5 d (winter: 6 d) | rễ màu xám bạc và vỏ thông khô; ngâm 10 phút, để ráo hoàn toàn | ngâm 10 phút | 11 |
| Basil (basil) | herb | đất nung 13 cm | trực tiếp | 1 d (winter: 1 d) | lớp đất mặt 1-2 cm đã khô | ~350 ml (cho đến khi thoát nước) | 12 |
## Lịch kiểm tra
| Ngày | Thứ | Mùa | Cây cần kiểm tra |
|---|---|---|---|
| 2026-11-02 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike, Zed |
| 2026-11-05 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-11-09 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-11-12 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
| 2026-11-16 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-11-19 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-11-23 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike, Zed |
| 2026-11-26 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
| 2026-11-30 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-12-03 | Thu | winter | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-12-07 | Mon | winter | Basil, Cal, Fernando, Peace lily, Pothos shelf, Spike |
| 2026-12-10 | Thu | winter | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
## Cảnh báo
| Mức độ | Cây | Lưu ý |
|---|---|---|
| HIGH | Peace lily | chậu không có lỗ thoát nước: nước đọng ở đáy làm thối rễ. Hãy thay chậu có lỗ, hoặc trồng cây trong chậu nhựa ươm đặt lọt bên trong chậu bọc ngoài và đổ hết nước đọng sau khi tưới 15 phút |
| LOW | Fernando | chậu đất nung làm cây này khô rất nhanh; đổi sang chậu nhựa hoặc chậu gốm tráng men sẽ giúp giữ ẩm đều hơn |
| LOW | Fernando | các ngày kiểm tra cố định khiến một số lượt kiểm tra bị trễ hơn một ngày (ví dụ: đến hạn 2026-11-07, lịch xếp vào 2026-11-09); hãy thêm một ngày kiểm tra trong tuần hoặc sờ thử đất xen kẽ giữa các buổi |
| LOW | Basil | các ngày kiểm tra cố định khiến một số lượt kiểm tra bị trễ hơn một ngày (ví dụ: đến hạn 2026-11-03, lịch xếp vào 2026-11-05); hãy thêm một ngày kiểm tra trong tuần hoặc sờ thử đất xen kẽ giữa các buổi |
Các khoảng thời gian trên giả định rằng cây đã bén rễ ổn định trong giá thể thoát nước tốt. Sau 2-3 tuần, hãy kéo dài khoảng cách kiểm tra nếu thấy đất vẫn còn ẩm ở hầu hết các lần kiểm tra, hoặc rút ngắn lại nếu lúc nào kiểm tra đất cũng đã khô kiệt.
FILE:scripts/watering_planner.py
#!/usr/bin/env python3
"""Houseplant watering schedule planner (Python 3.8+ standard library only).
Reads a CSV of plants (species or watering type, pot diameter, pot material, light,
drainage, optional last watering date) and builds a check calendar: how often to
check each plant in the current season, what "needs water" means for it, roughly how
much to give, and which plants to check on which date. Intervals stretch
automatically as the plan crosses into autumn and winter (or shrink into summer), by
hemisphere. Checks can be snapped to fixed weekdays (e.g. Mon,Thu) so the plan fits a
routine. Optional .ics export for a calendar app.
A check is not a watering: on each check, feel the soil and water only if the plant's
rule says so. The intervals are starting points; adjust them after two or three weeks
of real checks (see references/adjustment-factors.md).
Usage:
python3 watering_planner.py plants.csv [--start 2026-10-30] [--weeks 4]
[--hemisphere north|south] [--humidity low|normal|high]
[--check-days Mon,Thu] [--ics plan.ics] [--json]
python3 watering_planner.py --self-test
plants.csv columns: name, plant (species or type), pot_cm, pot_material
(plastic|glazed|ceramic|terracotta|fabric|self-watering), light (low|medium|bright|direct),
drainage (yes|no), last_watered (YYYY-MM-DD, optional), notes (optional).
Types: succulent, dry_tolerant, top_dry, evenly_moist, orchid, herb.
Exit codes: 0 = plan written, 1 = plan written with HIGH warnings (e.g. no drainage), 2 = bad input.
"""
import argparse, csv, datetime as dt, io, json, math, sys
PROFILES = {
# base days (spring, 15 cm plastic, medium light), winter factor, rule, share of pot volume per watering
"succulent": (10, 2.5, "soil dry all the way down (chopstick comes out clean and dry)", 0.15),
"dry_tolerant": (12, 2.0, "soil dry at least 3/4 of the way down", 0.15),
"top_dry": (6, 1.6, "top third of the soil dry (about 3-5 cm in a 15 cm pot)", 0.20),
"evenly_moist": (3, 1.3, "top 1-2 cm just dry; never let it dry out fully", 0.20),
"orchid": (7, 1.4, "roots silvery-grey and bark dry; soak 10 min, drain fully", 0.0),
"herb": (2, 1.2, "top 1-2 cm dry", 0.25),
}
SPECIES = {
"cactus": "succulent", "aloe": "succulent", "aloe vera": "succulent", "echeveria": "succulent",
"jade": "succulent", "jade plant": "succulent", "haworthia": "succulent", "string of pearls": "succulent",
"christmas cactus": "top_dry", "snake plant": "dry_tolerant", "sansevieria": "dry_tolerant",
"zz plant": "dry_tolerant", "zamioculcas": "dry_tolerant", "ponytail palm": "dry_tolerant",
"hoya": "dry_tolerant", "pothos": "top_dry", "monstera": "top_dry", "philodendron": "top_dry",
"rubber plant": "top_dry", "ficus elastica": "top_dry", "fiddle leaf fig": "top_dry",
"dracaena": "top_dry", "spider plant": "top_dry", "money tree": "top_dry", "pachira": "top_dry",
"chinese evergreen": "top_dry", "aglaonema": "top_dry", "dieffenbachia": "top_dry",
"yucca": "dry_tolerant", "bird of paradise": "top_dry", "alocasia": "top_dry", "anthurium": "top_dry",
"parlor palm": "top_dry", "peperomia": "dry_tolerant", "begonia": "top_dry",
"fern": "evenly_moist", "boston fern": "evenly_moist", "maidenhair fern": "evenly_moist",
"calathea": "evenly_moist", "prayer plant": "evenly_moist", "maranta": "evenly_moist",
"peace lily": "evenly_moist", "spathiphyllum": "evenly_moist", "fittonia": "evenly_moist",
"orchid": "orchid", "phalaenopsis": "orchid", "basil": "herb", "mint": "herb", "parsley": "herb",
}
MATERIAL = {"plastic": 1.0, "glazed": 1.0, "ceramic": 1.0, "metal": 1.0, "terracotta": 0.75,
"clay": 0.75, "unglazed": 0.75, "fabric": 0.7, "self-watering": 1.5}
LIGHT = {"low": 1.4, "medium": 1.0, "bright": 0.85, "direct": 0.7}
HUMIDITY = {"low": 0.85, "normal": 1.0, "high": 1.15}
SEASON_FACTOR = {"spring": 1.0, "summer": 0.85}
DAY_NAMES = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
class InputError(Exception):
pass
def season_of(d, hemisphere):
m = d.month if hemisphere == "north" else (d.month + 5) % 12 + 1
return {12: "winter", 1: "winter", 2: "winter", 3: "spring", 4: "spring", 5: "spring",
6: "summer", 7: "summer", 8: "summer"}.get(m, "autumn")
def pot_factor(cm):
if cm < 10:
return 0.6
if cm < 14:
return 0.8
if cm < 20:
return 1.0
if cm < 28:
return 1.3
return 1.6
def pot_litres(cm):
# straight-sided pot about 0.9x as tall as wide, minus ~10 % for the rim gap
r = cm / 2.0
return math.pi * r * r * (0.9 * cm) * 0.9 / 1000.0
def interval_days(p, season, humidity):
base, winter, _, _ = PROFILES[p["type"]]
# autumn sits halfway between spring and the plant's winter slow-down
sf = {"winter": winter, "autumn": (1 + winter) / 2}.get(season) or SEASON_FACTOR[season]
days = base * pot_factor(p["pot_cm"]) * MATERIAL[p["material"]] * LIGHT[p["light"]] * HUMIDITY[humidity] * sf
return max(1, min(45, int(round(days))))
def parse_date(s, what):
try:
return dt.date.fromisoformat(s.strip())
except ValueError:
raise InputError(f"bad date '{s}' for {what} (use YYYY-MM-DD)")
def load_plants(text):
rows = list(csv.DictReader(io.StringIO(text)))
if not rows:
raise InputError("plants CSV has no rows")
cols = {c.strip().lower(): c for c in rows[0] if c}
if "name" not in cols:
raise InputError("plants CSV needs at least a 'name' column (plus plant, pot_cm, pot_material, light, drainage)")
plants, warnings = [], []
for i, r in enumerate(rows, 2):
g = lambda k, d="": ((r.get(cols[k]) or "").strip() if k in cols else "") or d
name = g("name")
if not name:
raise InputError(f"row {i}: empty name")
kind = g("plant", g("type", "")).lower()
if kind in PROFILES:
ptype = kind
elif kind in SPECIES:
ptype = SPECIES[kind]
else:
ptype = next((v for k, v in SPECIES.items() if k in kind), None) if kind else None
if ptype is None:
ptype = "top_dry"
warnings.append(("MEDIUM", name, f"unknown plant '{kind or '?'}': using type top_dry; set the plant column to one of {', '.join(PROFILES)}"))
try:
pot = float(g("pot_cm", "0") or 0)
except ValueError:
raise InputError(f"row {i} ({name}): pot_cm must be a number of centimetres")
if pot <= 0:
pot = 15.0
warnings.append(("LOW", name, "no pot size given: assumed 15 cm"))
if pot > 80:
raise InputError(f"row {i} ({name}): pot_cm {pot} looks wrong (centimetres, not millimetres?)")
mat = g("pot_material", "plastic").lower()
if mat not in MATERIAL:
raise InputError(f"row {i} ({name}): pot_material '{mat}' (use {', '.join(MATERIAL)})")
light = g("light", "medium").lower().replace("bright indirect", "bright").replace("full sun", "direct")
if light not in LIGHT:
raise InputError(f"row {i} ({name}): light '{light}' (use low, medium, bright, direct)")
drainage = g("drainage", "yes").lower() not in ("no", "n", "false", "0")
last = parse_date(g("last_watered"), f"{name} last_watered") if g("last_watered") else None
p = {"name": name, "plant": kind or ptype, "type": ptype, "pot_cm": pot, "material": mat,
"light": light, "drainage": drainage, "last_watered": last, "notes": g("notes")}
plants.append(p)
if not drainage:
warnings.append(("HIGH", name, "pot has no drainage hole: water pools at the bottom and roots rot. Repot, or keep the plant in a nursery pot inside the cover pot and empty the cover pot 15 min after watering"))
if ptype == "succulent" and light == "low":
warnings.append(("MEDIUM", name, "succulent in low light: it will stretch and rot easily; move it to the brightest window and water even less"))
if ptype == "evenly_moist" and light == "direct":
warnings.append(("MEDIUM", name, "moisture-loving plant in direct sun: leaves scorch and soil dries within a day; move it out of direct sun"))
if ptype == "evenly_moist" and mat in ("terracotta", "clay", "unglazed", "fabric"):
warnings.append(("LOW", name, f"{mat} pot dries this plant very fast; a plastic or glazed pot keeps it evenly moist"))
if ptype == "orchid" and mat not in ("plastic",):
warnings.append(("LOW", name, "orchids are easiest in a clear plastic pot with drainage, so you can see the roots"))
if mat == "self-watering" and ptype in ("succulent", "dry_tolerant", "orchid"):
warnings.append(("MEDIUM", name, "self-watering pots keep the soil wet; not suited to plants that need to dry out"))
return plants, warnings
def amount_text(p):
_, _, _, share = PROFILES[p["type"]]
if p["type"] == "orchid":
return "soak 10 min"
if p["material"] == "self-watering":
return "refill reservoir"
ml = pot_litres(p["pot_cm"]) * 1000 * share
ml = int(round(ml / 50.0) * 50) or 50
return f"~{ml} ml (until it drains)" if p["drainage"] else f"~{ml // 2} ml, no more"
def snap(due, prev, allowed):
"""Allowed weekday nearest to the due date (ties go earlier), always after prev."""
if not allowed:
return due
best = None
for off in (0, -1, 1, -2, 2, -3, 3):
d = due + dt.timedelta(days=off)
if d > prev and d.weekday() in allowed:
best = d
break
if best is None:
best = max(due, prev + dt.timedelta(days=1))
while best.weekday() not in allowed:
best += dt.timedelta(days=1)
return best
def plan(plants, start, weeks, hemisphere="north", humidity="normal", check_days=None):
end = start + dt.timedelta(days=7 * weeks - 1)
allowed = {DAY_NAMES.index(x) for x in check_days} if check_days else set()
cal, per_plant, notes = {}, [], []
for p in plants:
s0 = season_of(start, hemisphere)
iv = interval_days(p, s0, humidity)
if p["last_watered"]:
due = p["last_watered"] + dt.timedelta(days=iv)
overdue = due < start
first = max(due, start)
else:
overdue, first = False, start
d = snap(first, start - dt.timedelta(days=1), allowed) if allowed else first
dates, prev = [], None
while d <= end:
dates.append(d)
cal.setdefault(d, []).append(p["name"])
step = interval_days(p, season_of(d, hemisphere), humidity)
due = d + dt.timedelta(days=step)
nd = snap(due, d, allowed)
if allowed and (nd - due).days > max(1, step // 5):
notes.append((p["name"], due, nd))
prev, d = d, nd
later = {season_of(x, hemisphere) for x in dates} - {s0}
per_plant.append({**p, "interval_now": iv, "season_now": s0,
"intervals_later": {s: interval_days(p, s, humidity) for s in sorted(later)},
"rule": PROFILES[p["type"]][2], "amount": amount_text(p),
"checks": [x.isoformat() for x in dates], "overdue": overdue})
return {"start": start, "end": end, "hemisphere": hemisphere, "humidity": humidity,
"check_days": check_days or [], "plants": per_plant,
"calendar": [(d, sorted(cal[d], key=str.lower)) for d in sorted(cal)], "late_snaps": notes}
def render(res, warnings):
st, en = res["start"], res["end"]
out = [f"# Houseplant watering plan: {st.isoformat()} to {en.isoformat()}", "",
f"Hemisphere: {res['hemisphere']} Season at start: {season_of(st, res['hemisphere'])} "
f"Humidity: {res['humidity']} Check days: {', '.join(res['check_days']) or 'any day'} Plants: {len(res['plants'])}", "",
"A check is not a watering: feel the soil and water only when the rule says so.", "",
"## Plants", "",
"| Plant | Type | Pot | Light | Check every | Water when | About | Checks |",
"|---|---|---|---|---|---|---|---|"]
for p in res["plants"]:
iv = f"{p['interval_now']} d"
if p["intervals_later"]:
iv += " (" + ", ".join(f"{s}: {v} d" for s, v in p["intervals_later"].items()) + ")"
pot = f"{p['pot_cm']:g} cm {p['material']}" + ("" if p["drainage"] else ", NO hole")
flag = " (overdue: check first day)" if p["overdue"] else ""
out.append(f"| {p['name']} ({p['plant']}){flag} | {p['type']} | {pot} | {p['light']} | {iv} | {p['rule']} | {p['amount']} | {len(p['checks'])} |")
out += ["", "## Calendar", "", "| Date | Day | Season | Check |", "|---|---|---|---|"]
for d, names in res["calendar"]:
out.append(f"| {d.isoformat()} | {DAY_NAMES[d.weekday()]} | {season_of(d, res['hemisphere'])} | {', '.join(names)} |")
if warnings or res["late_snaps"]:
out += ["", "## Warnings", "", "| Sev | Plant | Note |", "|---|---|---|"]
order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
for sev, name, msg in sorted(warnings, key=lambda w: (order[w[0]], w[1].lower())):
out.append(f"| {sev} | {name} | {msg} |")
seen = set()
for name, due, nd in res["late_snaps"]:
if name in seen:
continue
seen.add(name)
out.append(f"| LOW | {name} | check days push some checks more than a day late (e.g. due {due.isoformat()}, planned {nd.isoformat()}); add a check day or feel the soil in between |")
out += ["", "Intervals assume the plant is established in a free-draining mix. After 2-3 weeks, lengthen an interval if the soil is still moist at most checks, shorten it if it is always bone dry."]
return "\n".join(out) + "\n"
def to_ics(res, stamp):
lines = ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//houseplant-watering-schedule-planner//EN", "CALSCALE:GREGORIAN"]
for d, names in res["calendar"]:
nd = d + dt.timedelta(days=1)
lines += ["BEGIN:VEVENT", f"UID:plants-{d.strftime('%Y%m%d')}@watering-planner", f"DTSTAMP:{stamp}",
f"DTSTART;VALUE=DATE:{d.strftime('%Y%m%d')}", f"DTEND;VALUE=DATE:{nd.strftime('%Y%m%d')}",
"SUMMARY:" + ics_escape("Check plants: " + ", ".join(names)), "TRANSP:TRANSPARENT", "END:VEVENT"]
lines.append("END:VCALENDAR")
return "\r\n".join(fold(l) for l in lines) + "\r\n"
def ics_escape(s):
return s.replace("\\", "\\\\").replace(";", "\\;").replace(",", "\\,").replace("\n", "\\n")
def fold(line):
b = line.encode("utf-8")
if len(b) <= 75:
return line
parts, cur = [], b""
for ch in line:
e = ch.encode("utf-8")
if len(cur) + len(e) > (75 if not parts else 74):
parts.append(cur.decode("utf-8")); cur = b""
cur += e
parts.append(cur.decode("utf-8"))
return "\r\n ".join(parts)
def self_test():
H = "name,plant,pot_cm,pot_material,light,drainage,last_watered\n"
def run(rows, **kw):
plants, warns = load_plants(H + rows)
return plan(plants, kw.pop("start", dt.date(2026, 4, 6)), kw.pop("weeks", 4), **kw), warns
cases = []
def case(name, fn):
try:
ok = bool(fn())
err = ""
except Exception as e: # noqa
ok, err = False, repr(e)
cases.append((name, ok, err))
case("succulent checked less often than fern", lambda: run("A,cactus,15,plastic,medium,yes,\nB,fern,15,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] > run("A,cactus,15,plastic,medium,yes,\nB,fern,15,plastic,medium,yes,\n")[0]["plants"][1]["interval_now"])
case("base interval top_dry 15 cm plastic medium spring = 6", lambda: run("A,pothos,15,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] == 6)
case("small pot dries faster", lambda: run("A,pothos,9,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] < 6)
case("big pot lasts longer", lambda: run("A,pothos,30,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] > 6)
case("terracotta dries faster than plastic", lambda: run("A,pothos,15,terracotta,medium,yes,\n")[0]["plants"][0]["interval_now"] < 6)
case("low light lengthens, direct sun shortens", lambda: run("A,pothos,15,plastic,low,yes,\n")[0]["plants"][0]["interval_now"] > 6 > run("A,pothos,15,plastic,direct,yes,\n")[0]["plants"][0]["interval_now"])
case("winter stretches succulent 2.5x", lambda: run("A,cactus,15,plastic,medium,yes,\n", start=dt.date(2026, 1, 5))[0]["plants"][0]["interval_now"] == 25)
case("summer shortens", lambda: run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 7, 6))[0]["plants"][0]["interval_now"] == 5)
case("southern hemisphere: July is winter", lambda: season_of(dt.date(2026, 7, 1), "south") == "winter" and season_of(dt.date(2026, 1, 1), "south") == "summer")
case("season boundaries north", lambda: [season_of(dt.date(2026, m, 15), "north") for m in (2, 3, 5, 6, 8, 9, 11, 12)] == ["winter", "spring", "spring", "summer", "summer", "autumn", "autumn", "winter"])
case("interval grows across autumn->winter in plan", lambda: (lambda r: r["plants"][0]["intervals_later"].get("winter", 0) > r["plants"][0]["interval_now"])(run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 11, 16), weeks=4)[0]))
case("checks spaced by interval", lambda: run("A,pothos,15,plastic,medium,yes,\n")[0]["plants"][0]["checks"][:3] == ["2026-04-06", "2026-04-12", "2026-04-18"])
case("last_watered sets first check", lambda: run("A,pothos,15,plastic,medium,yes,2026-04-04\n")[0]["plants"][0]["checks"][0] == "2026-04-10")
case("overdue goes to start", lambda: (lambda p: p["overdue"] and p["checks"][0] == "2026-04-06")(run("A,pothos,15,plastic,medium,yes,2026-03-20\n")[0]["plants"][0]))
case("snap to check days (Mon,Thu)", lambda: all(dt.date.fromisoformat(x).weekday() in (0, 3) for x in run("A,pothos,15,plastic,medium,yes,\nB,cactus,12,terracotta,bright,yes,\n", check_days=["Mon", "Thu"])[0]["calendar"] and [x for p in run("A,pothos,15,plastic,medium,yes,\nB,cactus,12,terracotta,bright,yes,\n", check_days=["Mon", "Thu"])[0]["plants"] for x in p["checks"]]))
case("snap to nearest check day (Sun -> Mon)", lambda: snap(dt.date(2026, 4, 12), dt.date(2026, 4, 6), {0, 3}) == dt.date(2026, 4, 13))
case("snap tie goes earlier (Tue between Mon and Thu? no: Tue -> Mon)", lambda: snap(dt.date(2026, 4, 14), dt.date(2026, 4, 9), {0, 3}) == dt.date(2026, 4, 13))
case("snap never on or before the previous check", lambda: snap(dt.date(2026, 4, 7), dt.date(2026, 4, 6), {0, 3}) == dt.date(2026, 4, 9))
case("autumn between spring and winter", lambda: 6 < run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 10, 5))[0]["plants"][0]["interval_now"] < run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 12, 7))[0]["plants"][0]["interval_now"])
case("late snap noted for fast plant", lambda: len(run("A,basil,9,terracotta,direct,yes,\n", check_days=["Mon"])[0]["late_snaps"]) > 0)
case("no drainage -> HIGH warning and half amount", lambda: (lambda r: any(w[0] == "HIGH" for w in r[1]) and "no more" in r[0]["plants"][0]["amount"])(run("A,pothos,15,glazed,medium,no,\n")))
case("unknown plant -> top_dry with warning", lambda: (lambda r: r[0]["plants"][0]["type"] == "top_dry" and any("unknown plant" in w[2] for w in r[1]))(run("A,triffid,15,plastic,medium,yes,\n")))
case("species substring match", lambda: run("A,variegated monstera,15,plastic,medium,yes,\n")[0]["plants"][0]["type"] == "top_dry")
case("succulent low light warning", lambda: any("stretch" in w[2] for w in run("A,echeveria,10,terracotta,low,yes,\n")[1]))
case("fern in direct sun warning", lambda: any("scorch" in w[2] for w in run("A,boston fern,20,plastic,direct,yes,\n")[1]))
case("self-watering succulent warning", lambda: any("self-watering" in w[2] for w in run("A,cactus,15,self-watering,bright,yes,\n")[1]))
case("orchid amount is soak", lambda: run("A,orchid,12,plastic,bright,yes,\n")[0]["plants"][0]["amount"] == "soak 10 min")
case("amount scales with pot", lambda: int(run("A,pothos,25,plastic,medium,yes,\n")[0]["plants"][0]["amount"][1:].split()[0]) > int(run("A,pothos,12,plastic,medium,yes,\n")[0]["plants"][0]["amount"][1:].split()[0]))
case("low humidity shortens", lambda: run("A,fern,20,plastic,medium,yes,\n", humidity="low")[0]["plants"][0]["interval_now"] <= run("A,fern,20,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"])
case("interval never below 1 day", lambda: run("A,basil,6,fabric,direct,yes,\n", start=dt.date(2026, 7, 6), humidity="low")[0]["plants"][0]["interval_now"] >= 1)
case("missing pot size assumed 15", lambda: (lambda r: r[0]["plants"][0]["pot_cm"] == 15 and any("assumed 15" in w[2] for w in r[1]))(run("A,pothos,,plastic,medium,yes,\n")))
def bad(rows):
try:
load_plants(H + rows); return False
except InputError:
return True
case("bad material rejected", lambda: bad("A,pothos,15,wood,medium,yes,\n"))
case("bad light rejected", lambda: bad("A,pothos,15,plastic,dim,yes,\n"))
case("pot in mm rejected", lambda: bad("A,pothos,150,plastic,medium,yes,\n"))
case("bad date rejected", lambda: bad("A,pothos,15,plastic,medium,yes,30/10/2026\n"))
case("ics has one event per date, CRLF, escaped commas", lambda: (lambda r, t: t.count("BEGIN:VEVENT") == len(r["calendar"]) and "\r\n" in t and "\\," in t)(*(lambda r: (r, to_ics(r, "20261030T000000Z")))(run("A,pothos,15,plastic,medium,yes,\nB,fern,15,plastic,medium,yes,\n")[0])))
case("ics lines folded to 75 octets", lambda: all(len(l.encode()) <= 75 for l in to_ics(run("".join(f"Plant number {i},pothos,15,plastic,medium,yes,\n" for i in range(8)))[0], "20261030T000000Z").split("\r\n")))
passed = 0
for name, ok, err in cases:
passed += ok
print(("PASS " if ok else "FAIL ") + name + ("" if ok else f" {err}"))
print(f"{passed}/{len(cases)} passed")
return 0 if passed == len(cases) else 1
def main(argv=None):
ap = argparse.ArgumentParser(description="Build a houseplant watering check calendar")
ap.add_argument("plants", nargs="?")
ap.add_argument("--start", help="first day of the plan, YYYY-MM-DD (default today)")
ap.add_argument("--weeks", type=int, default=4)
ap.add_argument("--hemisphere", choices=["north", "south"], default="north")
ap.add_argument("--humidity", choices=list(HUMIDITY), default="normal", help="low = heating on / below ~35 %%")
ap.add_argument("--check-days", help="snap checks to these weekdays, e.g. Mon,Thu")
ap.add_argument("--ics", help="also write an .ics calendar file")
ap.add_argument("--json", action="store_true")
ap.add_argument("--self-test", action="store_true")
a = ap.parse_args(argv)
if a.self_test:
return self_test()
if not a.plants:
ap.error("give a plants CSV, or --self-test")
try:
start = parse_date(a.start, "--start") if a.start else dt.date.today()
if not 1 <= a.weeks <= 26:
raise InputError("--weeks must be 1..26")
days = None
if a.check_days:
days = [x.strip()[:3].title() for x in a.check_days.split(",") if x.strip()]
for x in days:
if x not in DAY_NAMES:
raise InputError(f"unknown weekday '{x}' in --check-days")
with open(a.plants, encoding="utf-8") as fh:
plants, warnings = load_plants(fh.read())
except (OSError, InputError, UnicodeDecodeError) as e:
print(f"error: {e}", file=sys.stderr)
return 2
res = plan(plants, start, a.weeks, a.hemisphere, a.humidity, days)
if a.ics:
stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
with open(a.ics, "w", encoding="utf-8", newline="") as fh:
fh.write(to_ics(res, stamp))
if a.json:
out = {**res, "start": res["start"].isoformat(), "end": res["end"].isoformat(),
"calendar": [{"date": d.isoformat(), "plants": n} for d, n in res["calendar"]],
"late_snaps": [{"plant": n, "due": d.isoformat(), "planned": p.isoformat()} for n, d, p in res["late_snaps"]],
"plants": [{**p, "last_watered": p["last_watered"].isoformat() if p["last_watered"] else None} for p in res["plants"]],
"warnings": [{"severity": s, "plant": n, "note": m} for s, n, m in warnings]}
print(json.dumps(out, indent=2))
else:
sys.stdout.write(render(res, warnings))
return 1 if any(w[0] == "HIGH" for w in warnings) else 0
if __name__ == "__main__":
sys.exit(main())So sánh các phương án đi làm - ô tô (xăng hoặc xe điện), phương tiện công cộng, xe đạp, xe đạp điện, đi bộ, kết hợp luân phiên theo ngày và chặng gửi xe đi tàu/buýt (park-and-ride) - theo tháng và năm kèm chi phí tiền mặt, thời gian di chuyển trọn gói từ cửa đến cửa, chi phí thời gian tính theo mức giá trị giờ của riêng bạn, chi phí mỗi chuyến và lượng phát thải CO2. Tự động chọn giữa vé tháng và trả tiền từng lượt dựa trên số ngày bạn đi, tách biệt chi phí vận hành xe với chi phí cố định, đồng thời hiển thị mức giá trị hòa vốn của một giờ. Bao gồm bộ tính toán bằng Python sử dụng thư viện chuẩn (stdlib) kèm tùy chọn --self-test.
---
name: commute-cost-comparison-calculator
description: So sánh các phương án đi làm - ô tô (xăng hoặc xe điện), phương tiện công cộng, xe đạp, xe đạp điện, đi bộ, kết hợp luân phiên theo ngày và chặng gửi xe đi tàu/buýt (park-and-ride) - theo tháng và năm kèm chi phí tiền mặt, thời gian di chuyển trọn gói từ cửa đến cửa, chi phí thời gian tính theo mức giá trị giờ của riêng bạn, chi phí mỗi chuyến và lượng phát thải CO2. Tự động chọn giữa vé tháng và trả tiền từng lượt dựa trên số ngày bạn đi, tách biệt chi phí vận hành xe với chi phí cố định, đồng thời hiển thị mức giá trị hòa vốn của một giờ. Bao gồm bộ tính toán bằng Python sử dụng thư viện chuẩn (stdlib) kèm tùy chọn --self-test.
---
# Công Cụ Tính Toán & So Sánh Chi Phí Đi Lại
Bạn giúp người dùng quyết định cách đi làm bằng việc đặt mọi phương án lên cùng một bàn cân: tốn bao nhiêu tiền mặt, lấy đi bao nhiêu thời gian trong cuộc sống của họ, và khoảng thời gian đó đáng giá bao nhiêu đối với họ. Bạn chỉ tính những khoản thực sự thay đổi theo lựa chọn (nhiên liệu, phí gửi xe, giá vé, chi phí xe đạp), loại bỏ các khoản họ đằng nào cũng phải trả trừ khi họ thực sự bán chiếc ô tô đó, và thể hiện sự đánh đổi bằng một con số rõ ràng: "lái xe tiết kiệm được 32 giờ mất đi mỗi năm và tốn thêm $3,697, vì vậy phương án này chỉ đáng giá nếu một giờ của bạn trị giá hơn $115".
## Các tệp trong kỹ năng này
- `scripts/commute_cost.py` - đọc tệp JSON kịch bản (khoảng cách, số ngày đi làm, giá trị thời gian, các phương án) và in ra bảng so sánh, tóm tắt nổi bật, giá trị thời gian hòa vốn và ghi chú cho từng phương án; hỗ trợ hệ mét (km, L/100 km) và hệ Anh-Mỹ (mi, mpg), xe điện (EV), vé tháng phương tiện công cộng có mức trần chi phí ngày và trợ cấp từ công ty, phương án kết hợp luân phiên theo ngày và chuyến đi nhiều chặng (chỉ dùng thư viện chuẩn của Python 3.8+)
- `references/cost-components.md` - mọi trường thông tin của phương án, những khoản cần đưa vào cho từng loại phương tiện, nơi tra cứu số liệu và các khoảng giá trị điển hình
- `references/time-value-and-assumptions.md` - cách chọn giá trị cho một giờ thời gian, thời gian có thể tận dụng trên phương tiện công cộng, những yếu tố chưa nằm trong tổng chi phí (sức khỏe, độ an toàn, thời tiết, sự linh hoạt) và cách chạy kiểm tra độ nhạy
- `templates/commute-comparison.md` - bản tóm tắt quyết định để gửi lại cho người dùng
- `examples/commute.json` - quãng đường đi làm 11 dặm với các phương án lái xe, xe buýt + tàu điện nhẹ (light rail), xe đạp điện, kết hợp xe đạp điện/phương tiện công cộng và gửi xe đi tàu/buýt (park-and-ride)
- `examples/comparison-output.md` - kết quả đầu ra thực tế của công cụ tính toán cho kịch bản đó
## Quy trình thực hiện
### 1. Thu thập thông tin thực tế
Khoảng cách một chiều, số ngày đi làm mỗi tuần (làm việc kết hợp hybrid ảnh hưởng rất lớn) và số tuần làm việc mỗi năm, số phút di chuyển từ cửa đến cửa cho mỗi phương án (bao gồm cả đi bộ, chờ đợi, gửi xe và chuyển tuyến: hãy hỏi thời gian chuyến đi thực tế chứ không chỉ lấy ước tính trên bản đồ), và thông tin theo từng phương tiện: mức tiêu thụ nhiên liệu của ô tô, giá xăng/dầu hoặc giá điện, phí gửi xe và cầu đường, liệu họ có giữ lại chiếc xe dù không lái đi làm hay không; giá vé lẻ phương tiện công cộng, giá vé tháng, mức trần chi phí ngày, trợ cấp của công ty; giá mua xe đạp hoặc xe đạp điện, tuổi thọ dự kiến và chi phí bảo dưỡng. Hãy hỏi xem một giờ thời gian của họ đáng giá bao nhiêu, hoặc đưa ra một mức mặc định (bằng một nửa mức lương theo giờ của họ) và trình bày phân tích độ nhạy.
### 2. Chạy công cụ tính toán
```
python3 scripts/commute_cost.py examples/commute.json
python3 scripts/commute_cost.py scenario.json --days-per-week 3
python3 scripts/commute_cost.py scenario.json --value-of-time 0 --json
python3 scripts/commute_cost.py --self-test
```
Mã thoát 0 = đã in bảng so sánh, 2 = dữ liệu đầu vào không hợp lệ (thiếu trường, tỷ lệ kết hợp cộng lại không bằng 1, loại phương tiện không xác định, giá âm). Nếu không chạy mã, hãy làm theo các công thức trong `references/cost-components.md`.
### 3. Đọc kết quả
- Bảng được sắp xếp theo tổng chi phí (tiền mặt + chi phí thời gian); dòng tiêu đề chỉ ra phương án rẻ nhất về tiền mặt, rẻ nhất khi tính cả thời gian và nhanh nhất.
- **Giá trị thời gian hòa vốn (Break-even value of time)** so sánh từng phương án với phương án rẻ nhất về tiền mặt: một phương án tốn nhiều tiền hơn chỉ đáng chọn nếu một giờ của bạn có giá trị cao hơn con số được hiển thị. "Never" (Không bao giờ) có nghĩa là phương án đó vừa tốn kém hơn vừa không tiết kiệm được thời gian hữu ích.
- Thời gian ngồi trên phương tiện công cộng mà bạn có thể tận dụng (đọc sách, xử lý email) được khấu trừ thông qua `usable_time_share`; cùng trường này cũng có thể dùng để cộng điểm cho thời gian đạp xe nếu việc đó thay thế cho thời gian tập thể dục mà đằng nào bạn cũng thực hiện. Hãy nêu rõ bạn đã áp dụng cách nào.
- Kiểm tra ghi chú về phương tiện công cộng: khi chỉ đi làm 2-3 ngày một tuần, vé tháng thường đắt hơn trả tiền từng lượt; công cụ tính toán sẽ tự chọn cách rẻ hơn và ghi chú rõ điều đó.
### 4. Bàn giao kết quả
Điền vào `templates/commute-comparison.md`: khuyến nghị gói gọn trong một câu, bảng so sánh, các mức giá trị hòa vốn, những yếu tố làm thay đổi câu trả lời (số ngày làm hybrid, giá nhiên liệu, phí gửi xe, giá trị thời gian), những yếu tố chưa được định giá bằng tiền, và gợi ý dùng thử (ví dụ: thử nghiệm phương án kết hợp trong hai tuần trước khi mua sắm bất cứ thứ gì).
## Ví dụ kết quả
11 dặm mỗi chiều, 5 ngày một tuần, 46 tuần, thời gian được định giá ở mức $20/giờ (`examples/commute.json`). Rẻ nhất về tiền mặt: xe buýt + tàu điện nhẹ ở mức $49/tháng sau khi trừ $50 trợ cấp từ công ty (vé tháng $99 rẻ hơn so với $105 tiền mua vé lẻ). Rẻ nhất khi tính cả thời gian: gửi xe đi tàu/buýt - park and ride ($95 tiền mặt, tổng cộng $361/tháng) vì 80 % thời gian chặng đi tàu có thể tận dụng làm việc khác. Lái xe vào trung tâm thành phố là nhanh nhất (28 phút) nhưng tốn $357/tháng với $12/ngày phí gửi xe và chỉ đáng giá nếu một giờ trị giá hơn $115. Xe đạp điện tốn trọn gói $67/tháng và không phát thải, nhưng không tiết kiệm thời gian hữu ích với các thông số này; phương án này sẽ chiến thắng nếu việc đạp xe thay thế cho thời gian tập gym. Xem `examples/comparison-output.md`.
## Quy tắc
- Chỉ tính những chi phí thực sự thay đổi theo lựa chọn; chỉ đưa chi phí bảo hiểm ô tô, đăng kiểm và lãi vay mua xe vào nếu người đó thực sự từ bỏ chiếc xe (`count_fixed`).
- Sử dụng thời gian thực tế từ cửa đến cửa, bao gồm cả đi bộ, chờ đợi, gửi xe và chuyển tuyến.
- Không bao giờ trình bày giá trị thời gian như một sự thật hiển nhiên: đó là lựa chọn riêng của mỗi người; hãy hiển thị ít nhất một lần chạy kiểm tra độ nhạy (ví dụ: `--value-of-time 0` và mức lương theo giờ của họ).
- Giữ các yếu tố sức khỏe, an toàn và thời tiết nằm ngoài tổng số tiền nhưng hãy đề cập đến chúng; không rao giảng đạo đức về việc đi ô tô hay xe đạp.
- Nêu rõ mọi giả định kèm theo con số cụ thể (giá nhiên liệu, phí gửi xe, khấu hao trên mỗi dặm) để người dùng có thể tự điều chỉnh.
- Sử dụng đơn vị tiền tệ và đơn vị đo lường đúng như người dùng đang sử dụng; không trộn lẫn dặm (miles) và kilômét (kilometres) trong cùng một kịch bản.
FILE:references/cost-components.md
# Các thành phần chi phí và trường thông tin phương án
Các trường của kịch bản: `currency` (USD, EUR, GBP, TRY, ...), `units` (`metric`: km, L/100 km, giá mỗi lít; `imperial`: dặm/miles, mpg, giá mỗi gallon Mỹ), `one_way_distance`, `days_per_week` (mặc định là 5), `weeks_per_year` (mặc định là 46: trừ ngày lễ, ngày nghỉ ốm, công tác), `value_of_time_per_hour`, `options`.
Mọi phương án đều có: `name`, `mode`, `minutes_one_way` (từ cửa đến cửa), `distance_one_way` tùy chọn (mặc định lấy theo khoảng cách của kịch bản), `usable_time_share` tùy chọn (0..1).
## Ô tô (`mode: car`)
| Trường | Ý nghĩa | Giá trị điển hình |
|---|---|---|
| `fuel_economy_mpg` / `fuel_l_per_100km` | mức tiêu thụ thực tế trên tuyến đường này (lái xe trong phố tốn hơn thông số nhãn) | 25-35 mpg / 6-9 L/100 km |
| `fuel_price` | tính theo mỗi gallon / mỗi lít | giá tại trạm xăng địa phương |
| `fuel: "diesel"` | sử dụng hệ số phát thải CO2 của dầu diesel | mặc định là xăng (petrol) |
| `kwh_per_100` + `electricity_price` | xe điện thay vì nhiên liệu đốt trong (kWh trên mỗi 100 dặm hoặc km) | 25-35 kWh/100 mi, 16-22 kWh/100 km |
| `grid_kg_co2_per_kwh` | cường độ phát thải của lưới điện để tính CO2 cho xe điện | mặc định 0.4; 0.05 với thủy điện/điện hạt nhân, 0.7 với lưới điện phụ thuộc nhiều vào than đá |
| `maintenance_per_distance` | lốp xe, bảo dưỡng định kỳ, sửa chữa trên mỗi dặm/km | $0.08-0.12/mi, 0.05-0.08/km |
| `depreciation_per_distance` | phần giá trị mất đi chỉ do số dặm/km chạy thêm (không tính hao mòn theo tuổi xe) | $0.05-0.15/mi |
| `parking_per_day`, `tolls_per_day` | tính trên mỗi ngày đi làm | phí gửi xe tại nơi làm việc có thể chiếm tỷ trọng lớn nhất |
| `fixed_per_year` + `count_fixed` | bảo hiểm, đăng kiểm, lãi vay, khấu hao theo tuổi xe; chỉ được tính khi `count_fixed` là true | chỉ đặt là true nếu việc đi làm là lý do duy nhất để sở hữu chiếc xe |
Chi phí nhiên liệu = 2 x khoảng cách x số ngày / mpg x giá (hoặc x L/100 km / 100 x giá). Khí thải CO2: xăng 2.35 kg/L (8.89 kg mỗi gallon Mỹ), dầu diesel 2.68 kg/L (10.18 kg/gal), xe điện tính bằng số kWh x hệ số phát thải lưới điện.
Các mức chi phí trọn gói trên mỗi dặm (định mức khấu trừ thuế theo dặm, báo cáo "Your Driving Costs" của AAA) đã bao gồm cả chi phí cố định; chúng làm phóng đại chi phí cận biên của việc đi làm khi đằng nào người dùng vẫn giữ lại chiếc xe.
## Phương tiện công cộng (`mode: transit`)
| Trường | Ý nghĩa |
|---|---|
| `fare_per_ride`, `rides_per_day` (mặc định là 2) | giá vé lẻ; cộng thêm một lượt cho mỗi lần chuyển tuyến có thu phí (không được miễn phí) |
| `daily_cap` | mức trần giá vé tối đa trong ngày, nếu hệ thống giao thông có áp dụng |
| `monthly_pass` | giá vé tháng; công cụ tính toán sẽ so sánh 12 vé tháng với chi phí trả từng lượt cho số ngày thực tế đi lại và chọn phương án rẻ hơn |
| `subsidy_per_month` | khoản trợ cấp từ công ty hoặc phúc lợi miễn thuế, được khấu trừ trực tiếp (không bao giờ giảm xuống dưới 0) |
| `co2_g_per_passenger_km` | mặc định 80 g; tàu điện 20-40, xe buýt chạy dầu diesel 80-120 ở mức tải trọng trung bình |
| `usable_time_share` | tỷ lệ thời gian chuyến đi bạn có thể đọc sách hoặc làm việc (có chỗ ngồi, không bị căng thẳng vì chuyển tuyến): 0.2-0.8 |
## Xe đạp, xe đạp điện, đi bộ (`mode: bike | ebike | walk`)
| Trường | Ý nghĩa | Giá trị điển hình |
|---|---|---|
| `purchase_price`, `life_years` | phân bổ đều trong suốt vòng đời sử dụng (mặc định 5 năm); không dùng cho đi bộ | xe đạp điện $1,500-3,500 |
| `maintenance_per_year` | lốp, xích, má phanh, quỹ thay pin cho xe đạp điện | $100-300 |
| `gear_per_year` | đèn, khóa, áo mưa, thay mũ bảo hiểm | $50-150 |
| `kwh_per_100`, `electricity_price` | chi phí sạc xe đạp điện | 1-2 kWh trên mỗi 100 dặm |
| `other_per_month` | phí gửi xe đạp, thuê tủ đồ, thẻ phòng tắm | 0-30 |
Chi phí sở hữu được tính toàn bộ ngay cả trong phương án kết hợp: bạn vẫn phải trả tiền mua chiếc xe đạp dù đi 3 hay 5 ngày một tuần.
## Kết hợp (`mode: mix`)
`"shares": {"E-bike": 0.6, "Bus + light rail": 0.4}` chia số ngày đi làm giữa các phương án khác nhau (tổng các tỷ lệ cộng lại bằng 1). Mỗi phần được tính chi phí theo đúng số ngày sử dụng của phần đó, vì vậy phần đi phương tiện công cộng trong 2 ngày một tuần thường sẽ chuyển sang hình thức trả tiền từng lượt. Hãy sử dụng chế độ này cho việc đạp xe phụ thuộc vào thời tiết, lái xe kết hợp (hybrid), hoặc những ngày đi chung xe (carpool).
## Nhiều chặng (`mode: multi`)
`"legs": [ {car leg}, {transit leg} ]` cùng với `transfer_minutes`. Mỗi chặng cần có `distance_one_way` và `minutes_one_way` riêng; chi phí và số phút sẽ được cộng dồn lại. Hãy dùng chế độ này cho hình thức gửi xe đi tàu/buýt (park and ride), xe đạp + tàu hỏa, hoặc đi bộ + xe buýt.
## Lấy số liệu ở đâu
- Mức tiêu thụ nhiên liệu: xem trên đồng hồ hành trình (trip computer) của ô tô trong suốt một tuần đi làm thực tế.
- Phí gửi xe và giá vé: trang bảng giá của đơn vị vận hành; kiểm tra các phúc lợi từ công ty (trợ cấp phương tiện công cộng trước thuế, quy đổi chỗ đỗ xe thành tiền mặt - parking cash-out).
- Thời gian từ cửa đến cửa: bấm giờ một chuyến đi thực tế cho mỗi chiều vào đúng khung giờ cao điểm đi làm; cộng thêm 5 phút dự phòng cho sự dao động khi tìm chỗ đỗ xe hoặc chờ tàu/buýt.
FILE:references/time-value-and-assumptions.md
# Giá trị thời gian và những yếu tố chưa nằm trong tổng chi phí
## Cách chọn giá trị thời gian
- Không có con số nào là đúng tuyệt đối: đó là mức giá trị mà một giờ đi làm thực sự mang lại cho chính người đó.
- Mốc tham chiếu phổ biến: khoảng một nửa mức lương thực nhận theo giờ đối với việc di chuyển cá nhân (hướng dẫn định giá thời gian di chuyển của Bộ Giao thông Vận tải Hoa Kỳ sử dụng mức 50 % thu nhập theo giờ cho các chuyến đi cá nhân tại địa phương; di chuyển công tác được định giá ở mức 100 %).
- Một người hưởng lương cố định, không thể kiếm thêm thu nhập nhờ giảm thời gian đi lại có thể chọn mức giá trị thấp hơn; một người làm nghề tự do (freelancer) có thể tính phí cho những giờ tiết kiệm được sẽ chọn mức cao hơn.
- Luôn trình bày phân tích độ nhạy: `--value-of-time 0` (chỉ tính tiền mặt), mức giá trị đã chọn, và toàn bộ mức lương theo giờ của họ. Nếu thứ hạng các phương án không thay đổi, quyết định đó là vững chắc.
## Thời gian có thể tận dụng
`usable_time_share` khấu trừ khoảng thời gian bạn có thể tận dụng làm việc khác. Hướng dẫn ước tính sơ bộ:
| Tình huống | Tỷ lệ |
|---|---|
| Lái xe, đạp xe giữa dòng giao thông, đứng trên xe buýt đông đúc | 0 |
| Đi xe buýt có chỗ ngồi, các chặng ngắn, phải chuyển tuyến | 0.2-0.4 |
| Đi tàu có chỗ ngồi và bàn làm việc, hơn 20 phút liên tục không phải đổi chuyến | 0.6-0.8 |
| Đạp xe hoặc đi bộ giúp thay thế cho thời gian tập thể dục mà đằng nào bạn cũng làm | 0.3-0.7 (hãy nêu rõ điều này) |
## Những yếu tố không nằm trong tổng số tiền (cần đề cập đến)
- **Sức khỏe:** đạp xe hoặc đi bộ thường xuyên gắn liền với sức khỏe tim mạch tốt hơn; một số người đánh giá rất cao lợi ích này, số khác lại không quan tâm. Hãy sử dụng `usable_time_share` nếu họ muốn quy đổi lợi ích này thành tiền.
- **Độ an toàn:** rủi ro tai nạn giao thông trên mỗi dặm khác nhau tùy theo phương tiện và tuyến đường; một làn đường dành riêng cho xe đạp có rào chắn bảo vệ sẽ làm thay đổi hoàn toàn bức tranh tổng thể.
- **Thời tiết và mùa vụ:** hãy sử dụng phương án kết hợp (ví dụ: 60 % số ngày đi xe đạp) thay vì giả định ngày nào cũng có thể đạp xe.
- **Độ ổn định (Reliability):** một chuyến tàu mất 40 phút với biên độ dao động 10 phút có thể tốt hơn một chuyến lái xe trung bình 30 phút nhưng dao động từ 25 đến 60 phút; hãy hỏi về các khoản phạt hoặc hậu quả khi trễ giờ (ví dụ: đón con muộn tại nhà trẻ).
- **Sự linh hoạt và giá trị quyền chọn:** việc có sẵn ô tô để tạt qua giải quyết việc vặt trên đường, hoặc cho các tình huống khẩn cấp; dịch vụ thuê xe theo giờ hoặc ngân sách đi taxi có thể thay thế cho những ngày hiếm hoi đó (cộng thêm vào mục `other_per_month`).
- **Mức độ căng thẳng và sự thoải mái:** đừng định giá bằng tiền, nhưng hãy hỏi người dùng về yếu tố này.
## Các kịch bản kiểm tra độ nhạy đáng thực hiện
- Làm việc kết hợp (Hybrid work): `--days-per-week 3` thường làm đảo ngược sự lựa chọn giữa vé tháng và trả tiền từng lượt, đồng thời khiến việc sở hữu chiếc ô tô thứ hai trở nên kém kinh tế hơn hẳn.
- Phí gửi xe: sự thay đổi về giá gửi xe (hoặc khoản tiền công ty thưởng khi không dùng chỗ đỗ xe) thường là đòn bẩy đơn lẻ lớn nhất.
- Giá nhiên liệu hoặc giá điện biến động +-25 %.
- Bán chiếc ô tô thứ hai: chạy lại tính toán với `count_fixed: true` cho phương án ô tô để thấy toàn bộ khoản tiền tiết kiệm được.
## Kiểm tra tính hợp lý trước khi trình bày
- Chi phí tiền mặt mỗi chuyến khi lái xe tối thiểu phải bằng chi phí nhiên liệu + phí gửi xe mỗi chuyến.
- Chi phí tiền mặt mỗi tháng cho phương tiện công cộng không được vượt quá giá vé tháng trừ khi vé tháng không bao phủ hết tuyến đường đó.
- Số giờ mỗi tháng = số phút một chiều x 2 x số ngày mỗi tháng / 60.
- Nếu phương án "chiến thắng" phụ thuộc vào một mức giá trị thời gian cách quá xa so với con số người dùng đưa ra, hãy nói rõ điều đó một cách thẳng thắn.
FILE:templates/commute-comparison.md
# Các phương án đi làm: <nhà> đến <nơi làm việc>
**Chuyến đi:** <11 dặm mỗi chiều, 5 ngày/tuần, 46 tuần/năm> **Giá trị thời gian áp dụng:** <$20/giờ (khoảng một nửa lương theo giờ)>
**Khuyến nghị:** <một câu, ví dụ: "Gửi xe đi tàu/buýt (Park and ride): $95/tháng tiền mặt, 40 phút từ cửa đến cửa, phần lớn thời gian đi tàu có thể tận dụng để xử lý email">
## Bảng so sánh (theo tháng)
| Phương án | Tiền mặt | Từ cửa đến cửa | Số giờ | Chi phí thời gian | Tổng cộng | CO2 kg/năm |
|---|---|---|---|---|---|---|
| <Park and ride> | <$95> | <40 min> | <25.6> | <$266> | <$361> | <999> |
| <Bus + light rail> | <$49> | <46 min> | <29.4> | <$411> | <$460> | <651> |
## Khi nào một phương án đắt đỏ hơn mới đáng tiền
| Phương án | Chi phí tăng thêm mỗi năm | Số giờ mất đi được tiết kiệm | Đáng giá nếu một giờ trị giá trên |
|---|---|---|---|
| <Drive downtown> | <$3,697> | <32> | <$115/hour> |
## Những yếu tố sẽ làm thay đổi câu trả lời
- <Làm việc kết hợp (3 ngày): vé tháng phương tiện công cộng không còn có lợi; trả tiền từng lượt ...>
- <Khoản tiền thưởng không dùng chỗ đỗ xe từ công ty sẽ khiến việc lái xe đắt thêm $230/tháng nữa>
- <Nếu chuyến đi bằng xe đạp điện thay thế cho việc tập gym, phương án xe đạp điện sẽ vươn lên ...>
## Những yếu tố chưa được định giá bằng tiền
- <sức khỏe, độ an toàn trên tuyến đường, những ngày thời tiết xấu, độ ổn định giờ giấc, nhu cầu dùng ô tô để đón con đi học>
## Các giả định
- <nhiên liệu $3.40/gal ở mức tiêu thụ 28 mpg; bảo dưỡng $0.10/mi; khấu hao theo số dặm $0.08/mi; phí gửi xe $12/ngày>
- <vé tháng phương tiện công cộng $99, trợ cấp từ công ty $50/tháng, 30 % thời gian đi xe buýt/tàu có thể tận dụng>
- <vẫn giữ ô tô để đi cuối tuần, do đó chi phí bảo hiểm và đăng kiểm không được tính vào>
## Bước tiếp theo
<Thử nghiệm phương án kết hợp trong hai tuần trước khi mua xe đạp điện; bấm giờ thực tế từng chuyến từ cửa đến cửa.>
FILE:examples/commute.json
{
"currency": "USD",
"units": "imperial",
"one_way_distance": 11,
"days_per_week": 5,
"weeks_per_year": 46,
"value_of_time_per_hour": 20,
"options": [
{
"name": "Drive downtown",
"mode": "car",
"minutes_one_way": 28,
"fuel_economy_mpg": 28,
"fuel_price": 3.4,
"maintenance_per_distance": 0.1,
"depreciation_per_distance": 0.08,
"parking_per_day": 12,
"tolls_per_day": 0,
"fixed_per_year": 1900,
"count_fixed": false
},
{
"name": "Bus + light rail",
"mode": "transit",
"minutes_one_way": 46,
"fare_per_ride": 2.75,
"monthly_pass": 99,
"subsidy_per_month": 50,
"usable_time_share": 0.3
},
{
"name": "E-bike",
"mode": "ebike",
"minutes_one_way": 42,
"purchase_price": 2200,
"life_years": 5,
"maintenance_per_year": 250,
"gear_per_year": 100,
"kwh_per_100": 1.5,
"electricity_price": 0.17
},
{
"name": "E-bike 3 days, transit 2 days",
"mode": "mix",
"shares": {"E-bike": 0.6, "Bus + light rail": 0.4}
},
{
"name": "Park and ride",
"mode": "multi",
"transfer_minutes": 6,
"legs": [
{"mode": "car", "distance_one_way": 4, "minutes_one_way": 10, "fuel_economy_mpg": 28, "fuel_price": 3.4,
"maintenance_per_distance": 0.1, "depreciation_per_distance": 0.08, "parking_per_day": 0},
{"mode": "transit", "distance_one_way": 7, "minutes_one_way": 24, "fare_per_ride": 2.75, "monthly_pass": 99,
"subsidy_per_month": 50, "usable_time_share": 0.8}
]
}
]
}
FILE:examples/comparison-output.md
# So sánh chi phí đi làm
Một chiều: 11 dặm Số ngày đi làm: 19.2/tháng (230/năm) Giá trị thời gian: $20.00/giờ Tiền tệ: USD
| Phương án | Tiền mặt / tháng | Tiền mặt / năm | Mỗi chuyến | Từ cửa đến cửa (một chiều) | Số giờ / tháng | Chi phí thời gian / tháng | Tổng cộng / tháng | CO2 kg / năm |
|---|---|---|---|---|---|---|---|---|
| Park and ride | $95.22 | $1,143 | $2.48 | 40 min | 25.6 | $266 | **$361** | 999 |
| Bus + light rail | $49.00 | $588 | $1.28 | 46 min | 29.4 | $411 | **$460** | 651 |
| E-bike 3 days, transit 2 days | $66.48 | $798 | $1.73 | 44 min | 27.9 | $487 | **$553** | 261 |
| E-bike | $66.91 | $803 | $1.75 | 42 min | 26.8 | $537 | **$604** | 0 |
| Drive downtown | $357 | $4,285 | $9.32 | 28 min | 17.9 | $358 | **$715** | 1,607 |
Được sắp xếp theo tổng chi phí (tiền mặt + chi phí thời gian).
## Điểm nổi bật
- Rẻ nhất về tiền mặt: **Bus + light rail** ($49.00/tháng).
- Rẻ nhất khi tính cả thời gian: **Park and ride** ($361/tháng ở mức $20.00/giờ).
- Nhanh nhất: **Drive downtown** (28 phút một chiều, 17.9 giờ/tháng).
## Giá trị thời gian hòa vốn (so với Bus + light rail, phương án rẻ nhất về tiền mặt)
| Phương án | Tiền mặt tăng thêm / năm | Số giờ mất đi tiết kiệm được / năm | Đáng giá nếu một giờ của bạn trị giá hơn |
|---|---|---|---|
| Drive downtown | $3,697 | 32 | $115/hour |
| E-bike | $215 | không có (mất thêm 75 giờ) | không bao giờ xét về chi phí: phương án này không tiết kiệm thời gian hữu ích |
| E-bike 3 days, transit 2 days | $210 | không có (mất thêm 45 giờ) | không bao giờ xét về chi phí: phương án này không tiết kiệm thời gian hữu ích |
| Park and ride | $555 | 87 | $6.35/hour |
## Ghi chú cho từng phương án
- **Drive downtown** (car): mỗi tháng: nhiên liệu/năng lượng $51.20, bảo dưỡng + khấu hao $75.90, phí gửi xe + cầu đường $230; chi phí cố định (bảo hiểm, đăng kiểm) không được tính: đằng nào bạn vẫn giữ lại chiếc xe
- **Bus + light rail** (transit): mỗi tháng: tiền vé $49.00; dùng vé tháng (rẻ hơn mức $105/tháng nếu trả từng lượt cho 19.2 ngày/tháng); đã khấu trừ trợ cấp từ công ty $50.00/tháng
- **E-bike** (ebike): mỗi tháng: tiền xe + bảo dưỡng $65.83, nhiên liệu/năng lượng $1.08; chi phí sở hữu được tính toàn bộ (chúng không giảm đi vào những ngày bạn không đạp xe)
- **E-bike 3 days, transit 2 days** (mix): E-bike 60 % số ngày (11.5/tháng): chi phí sở hữu được tính toàn bộ (chúng không giảm đi vào những ngày bạn không đạp xe); Bus + light rail 40 % số ngày (7.7/tháng): trả tiền từng lượt (mua vé tháng sẽ tốn tới $99.00/tháng cho 7.7 ngày/tháng)
- **Park and ride** (multi): chặng 2 (transit): dùng vé tháng (rẻ hơn mức $105/tháng nếu trả từng lượt cho 19.2 ngày/tháng); chặng 2 (transit): đã khấu trừ trợ cấp từ công ty $50.00/tháng
Chi phí thời gian = số giờ x giá trị thời gian x (1 - tỷ lệ chuyến đi bạn có thể tận dụng để đọc sách hoặc làm việc). Chưa bao gồm: lợi ích sức khỏe, rủi ro tai nạn, những ngày thời tiết xấu và giá trị quyền chọn của việc có sẵn ô tô; xem references/time-value-and-assumptions.md.
FILE:scripts/commute_cost.py
#!/usr/bin/env python3
"""Commute cost comparison calculator (Python 3.8+ standard library only).
Compares commute options - car (fuel or electric), transit, bike, e-bike, walking,
day-share mixes ("bike 3 days, train 2 days") and same-day multi-leg trips ("drive to
the station, then train") - per month and per year: cash cost, time spent, time cost at
your own hourly value, total, cost per trip and CO2. For transit it picks the cheaper of
pay-per-ride (with a daily cap) and a monthly pass for the days you actually ride; for
cars it separates running costs from fixed costs you would keep paying anyway. It also
prints break-even values of time: how much an hour must be worth to you before a faster,
dearer option pays off.
Usage:
python3 commute_cost.py scenario.json [--value-of-time 25] [--days-per-week 3] [--json]
python3 commute_cost.py --self-test
scenario.json: {"currency": "USD", "units": "imperial"|"metric", "one_way_distance": 11,
"days_per_week": 5, "weeks_per_year": 46, "value_of_time_per_hour": 20,
"options": [{"name": "...", "mode": "car|transit|bike|ebike|walk|mix|multi", ...}]}
See references/cost-components.md for every option field.
Exit codes: 0 = comparison printed, 2 = bad input.
"""
import argparse, json, sys
PETROL_CO2 = {"metric": 2.35, "imperial": 8.89} # kg CO2 per litre / per US gallon burned (diesel: 2.68 / 10.18)
DIESEL_CO2 = {"metric": 2.68, "imperial": 10.18}
KM_PER_UNIT = {"metric": 1.0, "imperial": 1.609344}
LABELS = {"energy": "fuel/energy", "running": "maintenance + depreciation", "parking_tolls": "parking + tolls",
"fixed": "fixed costs", "fares": "fares", "ownership": "bike + upkeep", "other": "other"}
MODES = {"car", "transit", "bike", "ebike", "walk", "mix", "multi"}
SYMBOLS = {"USD": "$", "EUR": "€", "GBP": "£", "TRY": "₺", "CAD": "C$", "AUD": "A$", "JPY": "¥", "INR": "₹"}
class InputError(Exception):
pass
def num(o, key, default=None, lo=0.0, hi=None, who=""):
v = o.get(key, default)
if v is None:
raise InputError(f"{who}: '{key}' is required")
if isinstance(v, bool) or not isinstance(v, (int, float)):
raise InputError(f"{who}: '{key}' must be a number")
if v < lo or (hi is not None and v > hi):
raise InputError(f"{who}: '{key}' = {v} is out of range" + (f" ({lo}..{hi})" if hi is not None else f" (>= {lo})"))
return float(v)
def car_cost(o, sc, days, who):
"""Annual cost dict for a car over `days` commute days."""
units = sc["units"]
d = num(o, "distance_one_way", sc["distance"], who=who) * 2 * days # user units per year
if "kwh_per_100" in o:
kwh = d / 100 * num(o, "kwh_per_100", who=who)
energy = kwh * num(o, "electricity_price", who=who)
co2 = kwh * num(o, "grid_kg_co2_per_kwh", 0.4, who=who)
else:
if units == "imperial":
vol = d / num(o, "fuel_economy_mpg", lo=1, who=who)
else:
vol = d / 100 * num(o, "fuel_l_per_100km", lo=0.5, who=who)
energy = vol * num(o, "fuel_price", who=who)
co2 = vol * (DIESEL_CO2 if o.get("fuel") == "diesel" else PETROL_CO2)[units]
running = d * (num(o, "maintenance_per_distance", 0, who=who) + num(o, "depreciation_per_distance", 0, who=who))
daily = days * (num(o, "parking_per_day", 0, who=who) + num(o, "tolls_per_day", 0, who=who))
fixed = num(o, "fixed_per_year", 0, who=who) if o.get("count_fixed", False) else 0.0
return {"energy": energy, "running": running, "parking_tolls": daily, "fixed": fixed,
"co2": co2, "notes": ([] if o.get("count_fixed", False) or not o.get("fixed_per_year") else
["fixed costs (insurance, registration) not counted: you keep the car anyway"])}
def transit_cost(o, sc, days, who):
rides = num(o, "rides_per_day", 2, lo=1, who=who)
fare = num(o, "fare_per_ride", who=who)
cap = o.get("daily_cap")
per_day = fare * rides if cap is None else min(fare * rides, num(o, "daily_cap", who=who))
payg_year = per_day * days
best, note = payg_year, "pay per ride"
if o.get("monthly_pass") is not None:
pass_year = num(o, "monthly_pass", who=who) * 12
months_days = days / 12
if pass_year < payg_year:
best, note = pass_year, f"monthly pass (cheaper than {fmt_plain(payg_year / 12, sc['sym'])}/month pay per ride at {months_days:.1f} days/month)"
else:
note = f"pay per ride (pass would cost {fmt_plain(pass_year / 12, sc['sym'])}/month at {months_days:.1f} days/month)"
subsidy = num(o, "subsidy_per_month", 0, who=who) * 12
best = max(0.0, best - subsidy)
km = num(o, "distance_one_way", sc["distance"], who=who) * 2 * days * KM_PER_UNIT[sc["units"]]
co2 = km * num(o, "co2_g_per_passenger_km", 80, who=who) / 1000
return {"fares": best, "co2": co2, "notes": [note] + ([f"employer subsidy {fmt_plain(subsidy / 12, sc['sym'])}/month deducted"] if subsidy else [])}
def bike_cost(o, sc, days, who, mode):
d = num(o, "distance_one_way", sc["distance"], who=who) * 2 * days
own = 0.0
if mode != "walk":
life = num(o, "life_years", 5, lo=0.5, who=who)
own = num(o, "purchase_price", 0, who=who) / life
own += num(o, "maintenance_per_year", 0, who=who) + num(o, "gear_per_year", 0, who=who)
energy = 0.0
if mode == "ebike":
kwh = d / 100 * num(o, "kwh_per_100", 1.2, who=who)
energy = kwh * num(o, "electricity_price", 0, who=who)
extra = num(o, "other_per_month", 0, who=who) * 12
return {"ownership": own, "energy": energy, "other": extra, "co2": 0.0,
"notes": ["ownership costs counted in full (they do not shrink on days you do not ride)"] if own else []}
def option_cost(o, sc, days, who):
mode = o.get("mode")
if mode == "car":
c = car_cost(o, sc, days, who)
elif mode == "transit":
c = transit_cost(o, sc, days, who)
elif mode in ("bike", "ebike", "walk"):
c = bike_cost(o, sc, days, who, mode)
else:
raise InputError(f"{who}: mode '{mode}' is not allowed here (use car, transit, bike, ebike, walk)")
minutes = num(o, "minutes_one_way", who=who, lo=1)
cash = sum(v for k, v in c.items() if k not in ("co2", "notes"))
return {"cash": cash, "minutes": minutes, "co2": c["co2"], "notes": c["notes"],
"usable": num(o, "usable_time_share", 0, hi=1, who=who),
"breakdown": {k: v for k, v in c.items() if k not in ("co2", "notes")}}
def evaluate(sc_raw, value_override=None, dpw_override=None):
if not isinstance(sc_raw, dict) or not isinstance(sc_raw.get("options"), list) or not sc_raw["options"]:
raise InputError("scenario needs an 'options' list")
units = sc_raw.get("units", "metric")
if units not in KM_PER_UNIT:
raise InputError("units must be 'metric' or 'imperial'")
cur = sc_raw.get("currency", "USD")
sc = {"units": units, "distance": num(sc_raw, "one_way_distance", who="scenario", lo=0.1),
"sym": SYMBOLS.get(cur, f"{cur} ")}
dpw = dpw_override if dpw_override is not None else num(sc_raw, "days_per_week", 5, lo=0.5, hi=7, who="scenario")
wpy = num(sc_raw, "weeks_per_year", 46, lo=1, hi=52, who="scenario")
days = dpw * wpy
vot = value_override if value_override is not None else num(sc_raw, "value_of_time_per_hour", 0, who="scenario")
by_name = {}
for i, o in enumerate(sc_raw["options"]):
if not isinstance(o, dict) or not o.get("name") or o.get("mode") not in MODES:
raise InputError(f"option {i + 1}: needs a 'name' and a 'mode' ({', '.join(sorted(MODES))})")
if o["name"] in by_name:
raise InputError(f"option name '{o['name']}' is used twice")
by_name[o["name"]] = o
results = []
for o in sc_raw["options"]:
who = o["name"]
if o["mode"] == "mix":
shares = o.get("shares")
if not isinstance(shares, dict) or not shares:
raise InputError(f"{who}: mix needs 'shares', e.g. {{\"Bike\": 0.6, \"Transit\": 0.4}}")
tot = sum(shares.values())
if abs(tot - 1) > 0.001:
raise InputError(f"{who}: shares add up to {tot:g}, not 1")
cash = co2 = hours = eff = 0.0
notes, parts = [], []
for nm, sh in shares.items():
if nm not in by_name or by_name[nm]["mode"] in ("mix",):
raise InputError(f"{who}: share '{nm}' must name another non-mix option")
sub = by_name[nm]
part = multi_cost(sub, sc, days * sh, nm) if sub["mode"] == "multi" else option_cost(sub, sc, days * sh, nm)
cash += part["cash"]; co2 += part["co2"]
h = part["minutes"] * 2 * days * sh / 60
hours += h; eff += h * (1 - part["usable"])
parts.append(f"{nm} {sh * 100:.0f} % of days ({days * sh / 12:.1f}/month): {part['notes'][0] if part['notes'] else 'as above'}")
minutes = hours * 60 / (2 * days)
results.append(row(who, "mix", cash, minutes, hours, eff, vot, co2, days, parts))
continue
part = multi_cost(o, sc, days, who) if o["mode"] == "multi" else option_cost(o, sc, days, who)
hours = part["minutes"] * 2 * days / 60
results.append(row(who, o["mode"], part["cash"], part["minutes"], hours, hours * (1 - part["usable"]), vot,
part["co2"], days, part["notes"], part.get("breakdown")))
return {"currency": sc_raw.get("currency", "USD"), "units": units, "one_way_distance": sc["distance"],
"days_per_year": days, "days_per_month": days / 12, "value_of_time_per_hour": vot,
"options": results, "break_even": break_even(results)}
def multi_cost(o, sc, days, who):
legs = o.get("legs")
if not isinstance(legs, list) or len(legs) < 2:
raise InputError(f"{who}: multi needs at least two 'legs'")
cash = co2 = minutes = 0.0
notes, usable_min = [], 0.0
for j, leg in enumerate(legs, 1):
if leg.get("mode") in ("mix", "multi"):
raise InputError(f"{who} leg {j}: legs cannot be mix or multi")
if "distance_one_way" not in leg:
raise InputError(f"{who} leg {j}: each leg needs its own 'distance_one_way'")
p = option_cost(leg, sc, days, f"{who} leg {j}")
cash += p["cash"]; co2 += p["co2"]; minutes += p["minutes"]
usable_min += p["minutes"] * p["usable"]
notes += [f"leg {j} ({leg['mode']}): {n}" for n in p["notes"]]
minutes += num(o, "transfer_minutes", 0, who=who)
return {"cash": cash, "co2": co2, "minutes": minutes, "notes": notes or ["legs summed"],
"usable": usable_min / minutes if minutes else 0.0}
def row(name, mode, cash, minutes, hours, eff_hours, vot, co2, days, notes, breakdown=None):
tcost = eff_hours * vot
return {"name": name, "mode": mode, "cash_year": cash, "cash_month": cash / 12, "minutes_one_way": minutes,
"hours_month": hours / 12, "lost_hours_month": eff_hours / 12, "time_cost_month": tcost / 12, "total_month": (cash + tcost) / 12,
"total_year": cash + tcost, "cost_per_trip": cash / (2 * days), "co2_kg_year": co2,
"notes": notes, "breakdown": breakdown or {}}
def break_even(results):
"""For each option, the hourly value of time at which it ties with the cheapest-cash option.
Uses lost hours (time you cannot use for reading or work), the same basis as the time cost."""
base = min(results, key=lambda r: r["cash_year"])
out = []
for r in results:
if r is base:
continue
extra = r["cash_year"] - base["cash_year"]
hours_saved = (base["lost_hours_month"] - r["lost_hours_month"]) * 12
if hours_saved > 0.01:
out.append({"option": r["name"], "vs": base["name"], "extra_cash_year": extra,
"hours_saved_year": hours_saved, "break_even_per_hour": extra / hours_saved})
else:
out.append({"option": r["name"], "vs": base["name"], "extra_cash_year": extra,
"hours_saved_year": hours_saved, "break_even_per_hour": None})
return out
def fmt_plain(v, sym="$"):
return f"{sym}{v:,.0f}" if abs(v) >= 100 else f"{sym}{v:,.2f}"
def render(res):
sym = SYMBOLS.get(res["currency"], res["currency"] + " ")
f = lambda v: fmt_plain(v, sym)
du = "mi" if res["units"] == "imperial" else "km"
out = [f"# Commute cost comparison", "",
f"One way: {res['one_way_distance']:g} {du} Commute days: {res['days_per_month']:.1f}/month ({res['days_per_year']:.0f}/year) "
f"Value of time: {f(res['value_of_time_per_hour'])}/hour Currency: {res['currency']}", "",
"| Option | Cash / month | Cash / year | Per trip | Door to door (one way) | Hours / month | Time cost / month | Total / month | CO2 kg / year |",
"|---|---|---|---|---|---|---|---|---|"]
rs = res["options"]
for r in sorted(rs, key=lambda r: r["total_month"]):
out.append(f"| {r['name']} | {f(r['cash_month'])} | {f(r['cash_year'])} | {f(r['cost_per_trip'])} | {r['minutes_one_way']:.0f} min | "
f"{r['hours_month']:.1f} | {f(r['time_cost_month'])} | **{f(r['total_month'])}** | {r['co2_kg_year']:,.0f} |")
cheapest = min(rs, key=lambda r: r["cash_year"])
best_total = min(rs, key=lambda r: r["total_year"])
fastest = min(rs, key=lambda r: r["minutes_one_way"])
out += ["", "Sorted by total (cash + time cost).", "",
"## Headline", "",
f"- Cheapest in cash: **{cheapest['name']}** ({f(cheapest['cash_month'])}/month).",
f"- Cheapest once time counts: **{best_total['name']}** ({f(best_total['total_month'])}/month at {f(res['value_of_time_per_hour'])}/hour).",
f"- Fastest: **{fastest['name']}** ({fastest['minutes_one_way']:.0f} min one way, {fastest['hours_month']:.1f} h/month)."]
out += ["", f"## Break-even value of time (vs {cheapest['name']}, the cheapest in cash)", "",
"| Option | Extra cash / year | Lost hours saved / year | Worth it if your hour is worth more than |", "|---|---|---|---|"]
for b in res["break_even"]:
if b["break_even_per_hour"] is None:
verdict = "never on cost: it does not save usable time" if b["extra_cash_year"] > 0 else "always: same cash, no more lost time"
hs = f"{b['hours_saved_year']:.0f}" if b["hours_saved_year"] >= 0 else f"none ({-b['hours_saved_year']:.0f} more lost)"
out.append(f"| {b['option']} | {f(b['extra_cash_year'])} | {hs} | {verdict} |")
else:
out.append(f"| {b['option']} | {f(b['extra_cash_year'])} | {b['hours_saved_year']:.0f} | {f(b['break_even_per_hour'])}/hour |")
out += ["", "## Notes per option", ""]
for r in rs:
bd = ", ".join(f"{LABELS.get(k, k)} {f(v / 12)}" for k, v in r["breakdown"].items() if v) if r["breakdown"] else ""
out.append(f"- **{r['name']}** ({r['mode']}): " + "; ".join(([f"per month: {bd}"] if bd else []) + r["notes"]))
out += ["", "Time cost = hours x value of time x (1 - share of the trip you can use for reading or work). "
"Not included: health benefits, accident risk, weather days and the option value of having a car; "
"see references/time-value-and-assumptions.md."]
return "\n".join(out) + "\n"
def self_test():
base = {"currency": "USD", "units": "metric", "one_way_distance": 10, "days_per_week": 5, "weeks_per_year": 48,
"value_of_time_per_hour": 20}
car = {"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_l_per_100km": 8, "fuel_price": 1.5,
"maintenance_per_distance": 0.05, "parking_per_day": 5}
tr = {"name": "Transit", "mode": "transit", "minutes_one_way": 40, "fare_per_ride": 2.5, "monthly_pass": 80}
bike = {"name": "Bike", "mode": "bike", "minutes_one_way": 35, "purchase_price": 1000, "life_years": 5, "maintenance_per_year": 100}
def ev(*opts, **kw):
sc = dict(base, options=list(opts)); sc.update(kw.pop("sc", {}))
return evaluate(sc, **kw)
def get(res, n):
return next(r for r in res["options"] if r["name"] == n)
cases = []
def case(name, fn):
try:
ok, err = bool(fn()), ""
except Exception as e: # noqa
ok, err = False, repr(e)
cases.append((name, ok, err))
# car: 240 days * 20 km = 4800 km; fuel 384 L * 1.5 = 576; maint 240; parking 1200 -> 2016/year
case("car annual cash (fuel + maintenance + parking)", lambda: abs(get(ev(car), "Car")["cash_year"] - 2016) < 0.01)
case("car CO2 petrol 2.35 kg/L", lambda: abs(get(ev(car), "Car")["co2_kg_year"] - 384 * 2.35) < 0.01)
case("diesel CO2 factor", lambda: abs(get(ev(dict(car, fuel="diesel")), "Car")["co2_kg_year"] - 384 * 2.68) < 0.01)
case("fixed costs excluded unless count_fixed", lambda: get(ev(dict(car, fixed_per_year=1500)), "Car")["cash_year"] == get(ev(car), "Car")["cash_year"])
case("fixed costs included with count_fixed", lambda: abs(get(ev(dict(car, fixed_per_year=1500, count_fixed=True)), "Car")["cash_year"] - 3516) < 0.01)
case("EV uses kWh and electricity price", lambda: abs(get(ev(dict(car, kwh_per_100=18, electricity_price=0.3, fuel_l_per_100km=None)), "Car")["breakdown"]["energy"] - 4800 / 100 * 18 * 0.3) < 0.01)
case("imperial mpg and $/gal", lambda: abs(get(ev({"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_economy_mpg": 30, "fuel_price": 3.6}, sc={"units": "imperial"}), "Car")["cash_year"] - 4800 / 30 * 3.6) < 0.01)
case("imperial CO2 8.89 kg/gal", lambda: abs(get(ev({"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_economy_mpg": 30, "fuel_price": 3.6}, sc={"units": "imperial"}), "Car")["co2_kg_year"] - 160 * 8.89) < 0.01)
# transit: per ride 5/day*240 = 1200 vs pass 960 -> pass
case("transit picks monthly pass when cheaper", lambda: abs(get(ev(tr), "Transit")["cash_year"] - 960) < 0.01)
case("transit picks pay-per-ride at 2 days/week", lambda: abs(get(ev(tr, dpw_override=2), "Transit")["cash_year"] - 5 * 96) < 0.01)
case("daily cap applied", lambda: abs(get(ev(dict(tr, monthly_pass=None, daily_cap=4)), "Transit")["cash_year"] - 4 * 240) < 0.01)
case("employer subsidy deducted, never below 0", lambda: get(ev(dict(tr, subsidy_per_month=100)), "Transit")["cash_year"] == 0)
case("bike ownership spread over life", lambda: abs(get(ev(bike), "Bike")["cash_year"] - 300) < 0.01)
case("ebike electricity", lambda: abs(get(ev(dict(bike, name="E", mode="ebike", kwh_per_100=1.5, electricity_price=0.3)), "E")["breakdown"]["energy"] - 4800 / 100 * 1.5 * 0.3) < 0.01)
case("walk has no purchase cost", lambda: get(ev({"name": "Walk", "mode": "walk", "minutes_one_way": 120, "purchase_price": 999}), "Walk")["cash_year"] == 0)
case("time cost = hours x value", lambda: abs(get(ev(car), "Car")["time_cost_month"] - 20 * 2 * 240 / 60 * 20 / 12) < 0.01)
case("usable time share discounts transit time", lambda: abs(get(ev(dict(tr, usable_time_share=0.5)), "Transit")["time_cost_month"] - 40 * 2 * 240 / 60 * 20 * 0.5 / 12) < 0.01)
case("value-of-time override", lambda: get(ev(car, value_override=0), "Car")["time_cost_month"] == 0)
case("per trip = annual cash / trips", lambda: abs(get(ev(car), "Car")["cost_per_trip"] - 2016 / 480) < 0.001)
# mix: bike 60 % of days, transit 40 % -> transit 96 days: per ride 480 vs pass 960 -> per ride
mixo = {"name": "Mix", "mode": "mix", "shares": {"Bike": 0.6, "Transit": 0.4}}
case("mix: bike ownership full + transit pay-per-ride on its days", lambda: abs(get(ev(bike, tr, mixo), "Mix")["cash_year"] - (300 + 480)) < 0.01)
case("mix: time weighted by days", lambda: abs(get(ev(bike, tr, mixo), "Mix")["minutes_one_way"] - (0.6 * 35 + 0.4 * 40)) < 0.01)
multi = {"name": "P+R", "mode": "multi", "transfer_minutes": 5, "legs": [
{"mode": "car", "distance_one_way": 3, "minutes_one_way": 8, "fuel_l_per_100km": 8, "fuel_price": 1.5, "parking_per_day": 2},
{"mode": "transit", "distance_one_way": 7, "minutes_one_way": 20, "fare_per_ride": 2.5, "monthly_pass": 80}]}
case("multi: legs summed + transfer", lambda: (lambda r: abs(r["minutes_one_way"] - 33) < 0.01 and abs(r["cash_year"] - (1440 * 0.08 * 1.5 + 480 + 960)) < 0.01)(get(ev(multi), "P+R")))
case("break-even: car vs cheapest", lambda: (lambda res: (lambda b: abs(b["break_even_per_hour"] - (2016 - 300) / ((35 - 20) * 2 * 240 / 60)) < 0.01)(next(b for b in res["break_even"] if b["option"] == "Car")))(ev(car, bike)))
case("break-even uses lost hours (usable transit time)", lambda: next(b for b in ev(dict(tr, usable_time_share=0.75, subsidy_per_month=60), bike)["break_even"] if b["option"] == "Bike")["break_even_per_hour"] is None)
case("break-even: slower and dearer -> None", lambda: next(b for b in ev(car, tr, bike)["break_even"] if b["option"] == "Transit")["break_even_per_hour"] is None)
case("render has headline and table", lambda: "Cheapest in cash: **Bike**" in render(ev(car, tr, bike)) and "| Car |" in render(ev(car, tr, bike)))
case("render uses currency symbol", lambda: "€" in render(ev(car, sc={"currency": "EUR"})))
def bad(*opts, **sc):
try:
ev(*opts, sc=sc); return False
except InputError:
return True
case("mix shares must sum to 1", lambda: bad(bike, tr, dict(mixo, shares={"Bike": 0.6, "Transit": 0.6})))
case("mix share must name an option", lambda: bad(bike, dict(mixo, shares={"Bike": 0.5, "Train": 0.5})))
case("unknown mode rejected", lambda: bad({"name": "Boat", "mode": "boat", "minutes_one_way": 5}))
case("duplicate names rejected", lambda: bad(car, car))
case("missing fuel economy rejected", lambda: bad({"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_price": 1.5}))
case("negative price rejected", lambda: bad(dict(car, fuel_price=-1)))
case("bad units rejected", lambda: bad(car, units="furlongs"))
case("usable share above 1 rejected", lambda: bad(dict(tr, usable_time_share=1.5)))
passed = 0
for name, ok, err in cases:
passed += ok
print(("PASS " if ok else "FAIL ") + name + ("" if ok else f" {err}"))
print(f"{passed}/{len(cases)} passed")
return 0 if passed == len(cases) else 1
def main(argv=None):
ap = argparse.ArgumentParser(description="Compare commute options per month and year, including time value")
ap.add_argument("scenario", nargs="?")
ap.add_argument("--value-of-time", type=float, help="override value_of_time_per_hour")
ap.add_argument("--days-per-week", type=float, help="override days_per_week (e.g. 3 for hybrid work)")
ap.add_argument("--json", action="store_true")
ap.add_argument("--self-test", action="store_true")
a = ap.parse_args(argv)
if a.self_test:
return self_test()
if not a.scenario:
ap.error("give a scenario JSON file, or --self-test")
try:
with open(a.scenario, encoding="utf-8") as fh:
sc = json.load(fh)
if a.days_per_week is not None and not 0.5 <= a.days_per_week <= 7:
raise InputError("--days-per-week must be 0.5..7")
res = evaluate(sc, a.value_of_time, a.days_per_week)
except json.JSONDecodeError as e:
print(f"error: scenario is not valid JSON: {e}", file=sys.stderr)
return 2
except (OSError, InputError, UnicodeDecodeError) as e:
print(f"error: {e}", file=sys.stderr)
return 2
print(json.dumps(res, indent=2) if a.json else render(res), end="" if not a.json else "\n")
return 0
if __name__ == "__main__":
sys.exit(main())