RFC: Phase-based recipe format


#1

Hi fellow farmers,
Currently, the Food Computer 2.0 runs environmental recipes defined as a time series in JSON. This is great for being able to define exactly what you want in your environment, down to the second, but it is difficult to author.

Luckily, our system supports plugging in adapters for multiple recipe formats. One format we’ve been thinking about is an easy-to-author “phase-based” YAML file. It would look something like this:

Some questions and thoughts:

  • Should phases in phase-based recipes always start with day?
  • What happens when the stage duration and phase duration don’t divide
    evenly? So for example, if a stage is 18hrs and happens to end at hr 6
    of a 12hr day cycle, and the next stage also starts with a day cycle,
    you could end up with a crazy long day when switching between stages
    10:36. Maybe we should define stages in terms of multiples of day/night cycles?
  • We could also just finish the full cycle before transitioning stages. So duration would be
    "roughly this many days".
  • Should day/night cycles have sensible defaults? (e.g. light is on by default during day unless otherwise specified). Leaning toward “yes”.
  • In addition to having a phase recipe adapter, we could create to/from conversion scripts so you can use either recipe format interchangeably.

Do you have other ideas for this format? How would you optimize it for ease-of-authorship? In what ways would you improve it?

Hat tip to @jake for this idea, and for authoring the original YAML example.


#2

First, I like the way it looks, nice and legible :slight_smile:

My thoughts:

  1. Would the day/night switch instantly, or would each parameter do an n [time unit] gradient descent/ascent towards day/night (Similar to how f.lux does day/night for screens) ?

  2. I think it would be sensible to have stage duration be in terms of how many days, and having day duration and night duration adding up to 24 hours.

  3. I think day/night “sensible defaults” might be good, given that they can be easily overridden. Especially since we can control the colors of lights to use, it might be interesting to have one spectrum of lighting on during the night, and all of them during the day or something.

  4. Conversion scripts make sense! I’d be interested in helping with that once the format is established.

  5. Maybe a description and url tag so it would start with something like

Recipe Name: "Default Basil"
Recipe Format: "Vector 1.0"
Version: "1.0"
Optimization: [General Purpose]
Date Created: 2016-12-13
Author: "OpenAg"
Author ID: 457028937405687305698723059
Recipe ID: 472309485702983470592837405
Description: "The original recipe used on the Media Lab farm."
URL: "https://gist.github.com/gordonbrander/228968a5b93142e3742119c60e3a3c00"

#3

@spaghet Great suggestions! BTW, I’m starting to sketch out conversion functions here, if you want to contribute https://github.com/OpenAgInitiative/phase_recipe.


#4

YAML is case-sensitive. Going all lowercase and underscores with keys is a bit uglier, but reduces the possibility of error (air_temperature vs Air Temperature).


#5

I like this approach! The readability lends itself well to troubleshooting or tinkering with recipes in addition to authoring them.

Should phases in phase-based recipes always start with day?

Given the option, I would personally always start with day. I plan to start very simply and naturally, so my cycles would always begin with a day and match the physical “real world” 24hr day/night closely. I would do this to avoid confusion between growth days and real days (it would be like counting digitally by starting with 0 so day 7 is actually day 8). But I can see the benefit to having the option to start where you please if you want a higher level of control. It looks like you’ve achieved that in this example by simply giving the day a value of 0 hours.

What happens when the stage duration and phase duration don’t divide evenly? Maybe we should define stages in terms of multiples of day/night cycles? We could also just finish the full cycle before transitioning stages.

Again, for me and my goal to keep it simple at the start, I would ensure that my day/night phases always added up to 24hrs. Letting phases finish would be an easy approach to that. But for tighter experimental control, this seems too simple. I would suggest adding a layer of hour granularity within the day or night phases. So additional blocks of code indented an additional layer under day could divide the day into as many sub-phases as the author requires.
So an 18 hour day could divide thusly:

- Early:
      Duration: 14 # Days
      Day:
             Phase 1:
                  Duration: 12 # Hours
                  Air Temperature: 20 # Celcius
                  Humidity: 50 # Relative
                  CO2: 2000 # PPM
                  pH: 6.5 # pH
                  Nutrient A: 100 # PPM
                  Nutrient B: 50 # PPM
                  Red Light: 200 # PPM
                  Blue Light: 100 # PAR
                  White Light: 0 # PAR
             Phase 2:
                  Duration: 6 # Hours
                  Air Temperature: 30 # Celcius
                  Humidity: 60 # Relative
                  CO2: 2000 # PPM
                  pH: 6.5 # pH
                  Nutrient A: 100 # PPM
                  Nutrient B: 50 # PPM
                  Red Light: 300 # PPM
                  Blue Light: 200 # PAR
                  White Light: 0 # PAR

Should day/night cycles have sensible defaults?

This makes sense. It’s a potential time saver, and a way to avoid simple mistakes.

In addition to having a phase recipe adapter, we could create to/from conversion scripts so you can use either recipe format interchangeably.

Yes! This is wise. There is likely to be a division of folks who prefer one over the other, so this ends the argument before it starts.

Nice work, @gordonb.


#6

Here’s a proof-of-concept script that will convert phased climate recipes into timeseries recipes https://github.com/OpenAgInitiative/openag_phased_recipe. Your contributions are welcome!


#7

This PR adds support for JSON phase-based recipes to the core software https://github.com/OpenAgInitiative/openag_brain/pull/98