We don't need to distinguish two cases for user and API data. We can directly use the completed objects
I agree.

In addition, we could let the user override the default process and specify the number of significant figures wanted in a query parameter : precision
Users can propose a precision, but how can it be valid if they don't not know the precision of the internal data of the calculator?

Correlated issue : Are they guidelines on the precision for internal data? If it is 3 significant digits by default, then we can document it and users can take it into account.

I am working on a solution with the 'auto' precision, let's iterate from that

from boaviztapi.

Hi @da-ekchajzer, I prefer your first proposal (adding dedicated units properties) rather than integrating in in the value field.
As you said, it simplifies later use / parsing of the values.

But IMHO we could have

• for standard (non verbose) output: a single json block of units (common to the result of API call), always included in the standard output (i.e. they represent the default units used for any field of the output)
• for verbose output: having each value sent with its unit
  something like:

{
"gwp":{"value":"30", "unit":"kgCO2eq"}
"adp":{"value":"10", "unit":"kgSbeq."}
"pe":{"value":"5", "unit":"MJ"}
}

Maybe this last model should even be the default (non verbose). From my perspective, not returning units is more a matter of optimization (reduced data exchange) but I think we should maybe rather be explicit by default.

Are there other considerations for not returning units ?

from boaviztapi.

Good point raised on the precision of those rounded values. Generally a result value should not be more precise than the inputs given to calculate it.

  "usage": {
    "hours_use_time": 1,
    "hour_electrical_consumption": 500
  }

In your example, the significant figures are 1 for the hours_use_time, and 3 for the hour_electrical_consumption, it reflects than the 'use' field should be only precise to 1 significant figure. If I'm not mistaken the results should be :

"gwp": {
    "manufacture": 3291,
   "use": 0.08,
   "unit":"kgCO2eq"
 }

In theory, the user should input "hours_use_time": 1.0 to increase precision to 2 significant figures.

In your example the "manufacture" is calculated without any user inputs, so we should be able to define its precision based on the internal data used from the calculator (TBD)

Solution

• Fix impacts units
• Rounding rule depends on user inputs
  • if inputs are provided, define precision based on the precision of the inputs
  • if no inputs are provided, define precision from the data used by boavizta

Does it make sense to you? Would that be easily understandable by the api consumers?

from boaviztapi.

We haven't addressed the unit issue until now because we haven't thought about it.

I personally like your proposition, since units are as important as the value itself. Besides, since we have different duration units, it can be inadequate to assess extreme durations. For instance, kgCO2eq is too big to assess the impact of an hour of cloud istances.

The only drawback I see is the complexification of the object.

The question for me now is : should we send this """complex object""" only in verbose mode ? Or for all impacts objects ?

from boaviztapi.

{
"gwp":{"value":"30", "unit":"kgCO2eq"}
"adp":{"value":"10", "unit":"kgSbeq."}
"pe":{"value":"5", "unit":"MJ"}
}

I like the way this object is precise and self-explaining. I'm not seeing too much complexity, I feel that it should the response by default.

By the way, in the server API, should the response be built to follow the same guideline? ie :

{
        "gwp": {
            "manufacture": 3292.0,
            "use": 696.0,
            "unit":"kgCO2eq"
        },
        "pe": {
            "manufacture": 41821.0,
            "use": "Not Implemented", 
            "unit":"MJ"
        },
        "adp": {
            "manufacture": 0.234,
            "use": "Not Implemented", 
            "unit":"kgSbeq."
        }
    }

In your opinion will the manufacture and use impacts be expressed always with the same unit?

from boaviztapi.

I like the way this object is precise and self-explaining. I'm not seeing too much complexity, I feel that it should the response by default.

I agree with your opinion to put the unit as close to the value as possible

In your opinion will the manufacture and use impacts be expressed always with the same unit ?

I think we should have the same units :

• 1 unit for all lifecycle steps
• Usage and manufacture can be directly summed
• Limit the number of embedded JSON objects

The client will be able to convert if he need

Problem - To Round or not to round ?

For instance, if I want the impact of the server for 1 hour :

{
  "model": {
  },
  "configuration": {
  },
  "usage": {
    "hours_use_time": 1,
    "hour_electrical_consumption": 500
  }
}

Will return a usage impact of 0 in kgCO2eq, since the value is rounded to the unit

"gwp": {
    "manufacture": 3292,
    "use": 0
}

Without rounding many digits, without considering significant figures

"gwp": {
   "manufacture": 3291.81656474227,
   "use": 0.07949550000000001,
   "unit":"kgCO2eq"
 }

Solution

• Fix impacts units
• Rounding rule :
  • if > 0 round(value, 2?)
  • if < 0 take the first 2? digits from the first digit != 0

"gwp": {
   "manufacture": 3291.81,
   "use": 0.079,
   "unit":"kgCO2eq"
 }

2? Could be an input provided by the user

What's your your opinion on this solution ?

from boaviztapi.

• Fix impacts units
• Rounding rule depends on user inputs
  • if inputs are provided, define precision based on the precision of the inputs
  • if no inputs are provided, define precision from the data used by boavizta

I agree with your solution !

To reformulate, we round according to the less precise attribute of the object used to measure the impact.

We don't need to distinguish two cases for user and API data. We can directly use the completed objects (completed_server, completed_cpu, completed_ssd, ...) which contains User input + API data.

In addition, we could let the user override the default process and specify the number of significant figures wanted in a query parameter : precision

Solution

• Fix impacts units
• If precision = auto or precision is None define precision based on completed object (user + API data)
• if ```(X = precision) is Number`` take X significant figures

Same questions ;)
Does it make sense to you? Would that be easily understandable by the api consumers?

from boaviztapi.