Problem

To be agnostic to cloud providers, we should provide a route with typical cloud instances.

Solution

The available instances could be segmented by price per hours. An empirical approach from several cloud providers could be conducted to create the archetypes.

Additional context or elements

POST /v1/cloud/model?archetype="$0.1-$0.5"

{
"usage":{
    "usage_location": "BEL",
    "workload":{
        "10":{
          "time": 0.1
        },
        "50":{
          "time": 0.2
        },
        "100":{
          "time": 0.1
        },
        "idle":{
          "time": 0.5
        }
    }
  }
}

Epic

Server

US

As an external user
I can retrieve the impact of my server
With the referenced data of Boavizta

Process

• If an archetype (name) is given by the user in the model object :
• The corresponding archetype (by name) is retrieve from the stored servers
• The server data sent by the user is kept, the missing data are set with the archetype value
• The regular bottom-up approach is applied.

API device storage

Devices are stored has DTO.

Problem

Today, only Manufacture and Usage impacts are implemented. We could add the impacts of device transportation.

Solution

We should consider two transportation phases :

• inter-state : mostly done by boat, plane and/or train
• intra-state : mostly done by trucks and trains

The functional unit should be kg per km.

"model":{
   "weight": 35,
    ...
},
"transport":{
   "interstate-km": 20204,
   "intrastate-km": 1000,
   "interstate-mode": "plane",
   "intrastate-mode": "truck"
}

interstate_impact = weight * interstate_km * allocation_factor(interstate_impact)
intrastate_impact = weight * intrastate_km * allocation_factor(intrastate_mode)

Default values

• A default weight should be provided per type of devices
• A default transport object should be provided :
  • default interstate should be China-Europe by plane (to maximize)
  • default intrastate should be set at 1000 km by trucks (ADEME/ARCEP approach + maximizing)

Additional context or elements

• Ecotransit methodology can be used to identify impacts factors
• Inspired by ADEME/ARCEP report

Problem

Usage impacts are computed for a certain period of time. The manufacture impacts are returned for all the life cycle of a device. We should provide a way to distribute manufacture impacts on a certain period of usage given by the user.

Solution

The easiest way to distribute manufacture impacts is linearly.

Different time distribution can be process :

• UseTime: Manufacture impacts are distributed linearly hover the use time
• Linear - Lifespan: Manufacture impacts are distributed linearly hover the lifespan

Distribution could be a query parameter :

• UpTime :
  (ManufactureImpact/TotalUpTimeInHour)*HourUsageServer
  Where TotalUpTimeInHour is the number of hours the server was up during its life

• Lifspan :
  (ManufactureImpact/LifespanInHour)*HourUsageServer
  Where LifespanInHour is the lifespan of the device in hours

• Total : All manufacture impacts is returned

Epic

Server

Route(s) involved

/v1/server/ref_data
/v1/server/bottom_up
/v1/server/

Description

The server data model contains all the data describing a server, except for its impact. When fully filled, a server object contains :

• The data needed to apply the bottom-up methodology
• Data to identify user servers close (model/configuration) to existing server in the database

Example

{
"model":{
   "brand": "Dell",
   "name": "R740",
   "type": "rack",
   "year": 2020
},
"configuration": {
    "cpu":{
        "number": 2,
        "core_number": 24
        "die": 0.245,
        "manufacturer": "Intel",
        "model": "",
        "cpu_family":
    },
    "ram":{
        "capacity": 32,
        "quantity": 12,
        "die": 1.79,
        "manufacturer": "Samsung",
        "model": "",
        "integrator": "Corsaire"
    },
    "ssd":{
        "capacity": 400,
        "quantity": 1,
        "die": 50.6,
        "manufacturer": "Samsung",
        "model": ""
        
    },
    "hdd":{
        "number": 0,
        "manufacturer": "Samsung",
        "model": ""
    },
   "power_supply":{
         "weight": 10,
         "quantity": 1
    }
}
add-method:
add-date:
}

Bug description

Swagger do not handle multiple exemples.

To Reproduce

• In boaviztapi > routers > server_router.py

CHANGE 

def server_impact_by_config(server_dto: ServerDTO = Body(None, example=server_configuration_examples["DellR740"]), verbose: bool = True):

TO 

def server_impact_by_config(server_dto: ServerDTO = Body(None, examples=server_configuration_examples["DellR740"]), verbose: bool = True):

and add another server to boaviztapi > routers >openapi_doc > examples.py

server_configuration_examples = {
    "empty_server"':{}
    "DellR740": {...

You will be able to change the example in http://localhost:5000/docs#/server/server_impact_by_config_v1_server_server_impact_by_config_description_post
but the content of body won't change.

Expected behavior

When another example is selected, the body should change accordingly.

Additional context

FastAPI issue on the topic :
tiangolo/fastapi#822

1. Choose a documentation tool
2. Create a documentation process
3. Implement the tool

Bug description

In the main documentation, the Demo page display an error.

To Reproduce

1. Open doc
2. go to Docs » TRY IT YOURSELF » DEMO
3. Display error: !! SWAGGER ERROR: File openAPI.json not found. !!

Expected behavior

Display Openapi / swagger UI in the doc.

Additional context

Due to a typo in /docs/docs/swagger.md where the openapi file is spelled with uppercase (openAPI.json instead of expected openapi.json)

Epic

Server

US

As an external user
I can send incomplete data describing server components
To receive its impacts (missing data will be dynamically determined)

Route(s) involved

components
server

Process

The user send data concerning the server components.
Matching components are found by the characteristics send by the user. FIND()
Default data are always the maximizing data (in terms of impacts)

FOREACH COMPONENTS
   IF component IS complete
       DO NOTHING
   ELSE IF FIND(component) == 0
       USE DEFAULT DATA 
   ELSE IF FIND(component) == 1
      USE FOUND COMPONENT
   ELSE IF FIND(component) > 1
       USE FOUND MAXIMIZING COMPONENT

Notes

Smart complete should be implemented at component level.
Each call to the component route could be smart completed.

Problem

Implement the impact of Amazon Web Services (aws) cloud instances

Solution

Using archetype. Each cloud instance type will be saved as an archetype. The user send the name of the instance under study to choose which archetype to load and usage data to precise the archetype.

Manufacture and usage are measured with the classic server methodology and divided by the number of instance type per server (depending on the instance type).

By default (in the archetype), the instance is load at 50% 100% of the time. This can be override by the user.

Additional context or elements

AWS archetype exemple (fake datas)

{
  "model":
  {
    "manufacturer": "AMAZON",
    "name": "a1-4xlarge",
    "type": "rack",
    "year": 2020
  },
  "configuration":
  {
    "cpu":
    {
      "units": 2,
      "core_units": 24,
      "die_size_per_core": 0.245
    },
    "ram":
    [
      {
        "units": 12,
        "capacity": 32,
        "density": 1.79
      }
    ],
    "disk":
    [
      {
        "units": 1,
        "type": "ssd",
        "capacity": 400,
        "density": 50.6
      }
    ],
    "power_supply":
    {
      "units": 2,
      "unit_weight": 2.99
    }
  },
  "usage": {
    "instance_per_server": 1,
    "max_power": 510,
    "hours_use_time": 1,
    "workload": {
        "10": {
            "time": 0,
            "power": 0.325
          },
         "50": {
            "time": 1,
            "power": 0.7235
          },
          "100": {
        "time": 0,
            "power": 1
          }
          "idle": {
            "time": 0,
            "power": 0.2
          }
    }
  }
}

Example of request
querry parameter : a1-4xlarge

{
  "year_use_time": 2,
  "usage_location": "FRA",
  "workload": {
     "10": {
        "time": 0.2
      },
      "50": {
        "time": 0.3
      },
      "100": {
        "time":  0.5
      },
      "idle": {
        "time":  0
      }
    }
}

Bug description

When an empty configuration server is given default case is not set

To Reproduce

POST /v1/server/

{}

**No CASE component in verbose object **

"verbose": {
"CPU-1": {
      "unit": 2,
      "core_units": 24,
      "die_size_per_core": 0.245,
      "impacts": {
        "gwp": 44,
        "pe": 650,
        "adp": 0.04
      }
    },
    "SSD-1": {
      "unit": 1,
      "capacity": 1000,
      "density": 48.5,
      "impacts": {
        "gwp": 52,
        "pe": 640,
        "adp": 0.002
      }
    },
    "RAM-1": {
      "unit": 24,
      "capacity": 32,
      "density": 0.625,
      "impacts": {
        "gwp": 2832,
        "pe": 35328,
        "adp": 0.12
      }
    },
    "POWER_SUPPLY-1": {
      "unit": 2,
      "unit_weight": 2.99,
      "impacts": {
        "gwp": 146,
        "pe": 2104,
        "adp": 0.05
      }
    },
    "MOTHERBOARD-1": {
      "unit": 1,
      "impacts": {
        "gwp": 66,
        "pe": 836,
        "adp": 0.004
      }
    },
    "ASSEMBLY-1": {
      "unit": 1,
      "impacts": {
        "gwp": 7,
        "pe": 69,
        "adp": 0
      }
    }
}

Expected behavior

If no configuration is given, a default CaseComponent should be added

JSON OUTPUT

"verbose": {
"CPU-1": {
      "unit": 2,
      "core_units": 24,
      "die_size_per_core": 0.245,
      "impacts": {
        "gwp": 44,
        "pe": 650,
        "adp": 0.04
      }
    },
    "SSD-1": {
      "unit": 1,
      "capacity": 1000,
      "density": 48.5,
      "impacts": {
        "gwp": 52,
        "pe": 640,
        "adp": 0.002
      }
    },
    "RAM-1": {
      "unit": 24,
      "capacity": 32,
      "density": 0.625,
      "impacts": {
        "gwp": 2832,
        "pe": 35328,
        "adp": 0.12
      }
    },
    "POWER_SUPPLY-1": {
      "unit": 2,
      "unit_weight": 2.99,
      "impacts": {
        "gwp": 146,
        "pe": 2104,
        "adp": 0.05
      }
    },
    "MOTHERBOARD-1": {
      "unit": 1,
      "impacts": {
        "gwp": 66,
        "pe": 836,
        "adp": 0.004
      }
    },
    "ASSEMBLY-1": {
      "unit": 1,
      "impacts": {
        "gwp": 7,
        "pe": 69,
        "adp": 0
      }
    },
    "CASE-1": {
      "unit": 1,
      "case_type": "used_value": "rack",
      "impacts": {
        "gwp": 150,
        "pe": 2200,
        "adp": 0.02
      }
}

Additional context

Add an empty ComponentCase into the default server configuration in model/devices.py line 142 get_default_configuration_component_list

Epic

ALL

TODO

• Create unit tests for bottom-up routes
• Setup test in github workflow

Problem

In order to identify the nature of each server archetypes we should provide a small text that describe it.

Solution

v1/server/all_default_models should return the description and the identifier that will be used in the request. We could also add other attributes that describes the archetype, year for instance.

Implementation

• Add a description attribute in model
• Fill the description and year attribute in the archetype
• v1/server/all_default_models should return something like :

{
   "archetype-1": {
      "description" : "description",
      "year": 2019
   },
   "archetype-2": {
      "description" : "description",
      "year": 2019
   },
   "archetype-3": {
      "description" : "description",
      "year": 2019
   },
}

Problem

In cloud environments, an instance is a layer of abstraction for multiple resources :

• Client allocated corresponding to the resources paid by the client
• CSP & control plane corresponding to the computing power used to monitor, secure and orchestrate the resources
• unalocated ressources resulting from :
  • the need for redundancy. In that case, unallocated resources depends on the number of redundancy and the number of datacenters. If two datacenters are available, redundancy will use 50% of the potential compute resources in order to back up each other. If three datacenters are available, redundancy will use 33% of the potential compute resources.
  • the lack of optimization.
• Support equipment corresponding to the cooling and other overhead that supports the compute resources.

Today, cloud instances impacts are measured based exclusively on the impacts of Client allocated resources. We should be able to retrieve the overall impacts of a cloud instance.

Solution

client_allocated_impacts

Already implemented #29

unalocated_ressources_impacts

Scope 3 = client_allocated_impacts*(1/nb_redondancy_datacenter)
Scope 2 = client_allocated_impacts(IDLE)/nb_redondancy_datacenter

Only redundancy is taken in consideration, we should also consider unaffected resources waiting for clients.

CSP_control_plane_impacts

• Those resources could be measure as function of the overall resources, i.e the resources represent X% of the compute power of a cloud provider, the impact represent X% of the impacts :

Scope 3 = ((unalocated_ressources_impacts + client_allocated_impacts) * X)/100-X
Scope 2 = ((unalocated_ressources_impacts + client_allocated_impacts) * X)/100-X

• In reality, those resources are not linearly dependent on the client load but on the overall quantity of load. Since unalocated_ressources_impacts is dependent on the client load this approach will make CSP_control_plane_impacts also dependent on the client load. Another approach would be to allocate a fix impact per instance :

Scope 3 = fix_impact_per_instance
Scope 2 = fix_impact_per_instance

Support equipments

Scope 2 = (compute_impact * PUE) / compute_impact

Scope 3 = ?

Problem

Current documentation contains interesting topics (tutorials, explanation of methodology, API reference documentation) but the documentation is a bit difficult to navigate.

• topics are sometime mixed
• lack of use cases (representing end-users goals)
• the how to use section may be a bit too much technical (or wording use tech terms like 'router' ).
• order of topics may not be optimal.
• 🧭 newly on-boarded users may feel lost

Solution

Adapt documentation to use the Diataxis documentation format: https://diataxis.fr/introduction/
This is a structure of documentation that is commonly used in opensource projects.

The tooling remain the same but the structure would be:

• tutorial (quick on-boarding, easy and instant gratification tutorial to show the basics of what API offers)
• How-to-guide (more in detail task focused tutorials)
• explanation (explaining methodology, global functional and tech design, rationale behind the main choices done)
• reference (detailed referenced doc like routes, parameter formats a.s.o).

It could also be interesting:

• to provide some typical use cases / stories linked to a persona.
• use more diagrams, ideally with tools like mermaid or plantUML for tech diagrams.

Alternatives

• executable API documentation (i.e. to allow user to try functionalities). But this is complex (and custom) to put in place or maintain. Not sure it is worth the effort.

Additional context or elements

• The documentation framework https://diataxis.fr/introduction/
• The book The Design of Web APIs by Arnaud Lauret https://apihandyman.io/

Epic

Server

US

As an external user
I can retrieve the impact of my server
With the bottom-up methodology of Boavizta

Route(s) involved

/v1/server/bottom-up

Process

The user send data concerning the server (model, brand, type, CPU type, CPU number, stockage capacity, ...). If all the data needed to apply the methodology has been given by the user, the impact is calculated and sent back to the user. If not, default values are used

Bug description

Usage components are not treated in the verbose service.

To Reproduce

Any request on a device with verbose = true won't return any information on usage components.

Expected behavior

The verbose service should treat usage component like any other components.

/!\ Usage components has attribute of dict type, a recursive function must be applied to handle embedded attributes.

Problem

Server archetypes are implemented, but configurations have been randomly set.

Solution

We should set the server archetypes with a configuration that sustain real typology of servers.

Problem

In some cases, some cloud providers doesn't reserve the resources paid for the cloud instances. The resource is shared between several instances. Thus, we shouldn't allocate 100% of the configuration of the scope3 impact of the instance configuration.

Solution

We consider that only CPUs are shared, thus we should allocate only a part of the CPU scope3 impacts to the instance. We should take into consideration how many instances are sharing one CPU : nb_instances_per_CPU

Instance Scope3 = BoaviztaScope3 – (BoaviztaScope3CPU * [(nb_instances_per_CPU-1) / nb_instances_per_CPU])

We should give a default value to nb_instances_per_CPU let's say 4 (i.e. we allocate the scope3 impacts of 1/4)

Question

• Does the overcommitment affect the scope2 ?
• Does the overcommitment is made only with CPU ?

Problem

Complete_with_archetype won't complete workload data if workload exist but is not complete. It's an issue if I want to give a time per workload, but I don't have the power per load (case of cloud).

Example : since workload exist, the object will be used without replacing power

  "usage": {
    "hours_use_time": 1,
    "workload": {
     "10": {
        "time": 0.2,
      },
      "50": {
        "time": 0.3
      },
      "100": {
        "time":  0.5
      },
      "idle": {
        "time":  0
      }
    }
}

ERROR : hours_electrical_consumption += values["time"] * values["power"] * self.max_power KeyError: 'power'

Solution

complete_with_archetype for usage components should have a recursive way of treating attributes for usage only.

Additional context or elements

Such use case should be unit tested

Problem

Usage impact PE and ADP are not implemented because electrical impact factors for ADP and PE are not set (set to 0).

Solution

Find medium electrical impact factors for ADP and PE per country.

Alternatives

Find medium electrical impact factors for ADP and PE for Europe.

Additional context or elements

For ADP : kgSbeq./kWh
For PE : MJ/kWh

Problem

We want to retrieve the impacts of manufacture and usage of screens. According to recent study, screens account for a great part of the ICT EM impacts in France and Europe.

Solution

Several solutions could be used

Using archetypes

Defining some archetypes. Impacts foreach archetypes would be taken from :

• Manufacturer PCF (Boavizta database)
• ADEME BASE IMPACT
• LCA
• Other

Query example :
Pre-recorded archetype OLED screen, size between 22" to 26"

{
   "archetype":"OLED-22-26",
   "hour_usage": 3
}

Defining a formula

We could define impacts factors based on screen characteristics, as we did for servers components:

• Screen Size
• Type (TV, Screen)
• Technology (OLED, LED, 4K, ...)
• ...

This impacts factors could be defined empirically based on Boavizta database or Fixometer reference data - 2021
records

To do so we need to explore the data and see to what extent characteristics influence the impacts of a screen.
Archetype could still be used we pre-recorded characteristics

Querry exemple :

{
  "technology": "OLED",
  "size": 22,
  "type": "screen",
   "hour_usage": 3
}

If you have other ideas feel free !

Additional context or elements

In both cases, it would be nice find multicriteria data about screen

Problem

We want to retrieve the impacts of manufacture and usage of data transfer over the internet (mobile and fix network). Private network are outside the scope of this issue.

Solution

Several strategies exist in the literature to measure the impact of a data transfer over a mobile or fix network. This issue is highly inspired by this article. Feel free to read it if you need a complete explanation of the different approaches.

ADEME - NEGAOCTET approach

Source : ADEME PCR

Criteria : Carbon
Life phase(s) : all life cycle
Primary objective : Reporting for FAI clients

Mobile network : impact of a client is linear as a function of the consumed data

Empreinte carbone (en gCO2e/mois) = Quantité de données consommées par l’utilisateur (en Go/mois) x Ratio moyen majorant représentatif de l’impact du « Réseau Mobile France » (en gCO2e/Go)*

*au 1er janvier 2022 cette valeur est estimée à 49.4gCO2e/Go (gramme CO2 équivalent par Gigaoctet)

Fix network : impact of a client is linear as a function of time (month)

Empreinte carbone (en gCO2e/month) = Impact moyen de la consommation Internet fixe d’un Français (en gCO2e/mois)**

** au 1er janvier 2022 cette valeur est estimée à 4.1 kgCO2e/mois par abonné. L’utilisation des réseaux fixes est à privilégier dès que possible.

Exemple of querry using default factors :

{
"network_type": "mobile"
"data": 45
}

{
"network_type": "fix",
"subscriber_number": 1,
"hour_use": 1
}

+ :

• Uses all the life cycle
• Impacts factors used to apply a French legislation

- :

• Mono criteria
• In reality, impact and data are not proportional
• No documentation on the methodology:
  • usage and manufacture impact can't be distinguished
  • specific carbon intensity can't be used (french carbon intensity will always be applied)

POWER MODEL

Source : Malmodin's paper : page 87, DIMPACT study

Criteria : Power consumption (multiple impact can be retrieved with electrical impact factors)
Life phase(s) : Usage only
Primary objective : Measure the marginal effect on power consumption of a change in data consumption

Fix network : per user (1 user = 1 device) per line

• Access network + CPE :

(idle_power/nb_users_per_line) + (((idle_power-max_power)/100)*average_bit_usage_per_second)/nb_user_in_usage 

With malmodin's power factors :
(16.5 W/nb_users_per_line) + (0.02 W/Mbps / nb_user_in_usage) * average_bit_usage_per_second 

• Core network :

SUM((((idle_power/nb_line)/nb_users_per_line) + ((((idle_power-max_power)/100)*average_bit_usage_per_second)/nb_lines_in_usage)nb_user_in_usage) FOREACH hops) 

With malmodin's power factors :
(1.5 W/nb_users_per_line) + (0.03 W/Mbps / nb_user_per_line) * average_bit_usage_per_second 

Mobile network : per line (1 line = 1 device)

• Access network (Base station) :

(idle_power/nb_device) + ((idle_power-max_power)/100)*average_bit_usage_per_second))

With malmodin's power factors :
1 W + 0.02 W/Mbps * average_bit_usage_per_second

• Core network :

SUM(((idle_power/nb_device) + ((idle_power-max_power)/100)*average_bit_usage_per_second) FOREACH hops)

With malmodin's power factors :
0.2 W + 0.03 W/Mbps * average_bit_usage_per_second

Exemple of querry using default factors :

{
"network_type": "mobile",
"average_bit_usage_per_second": 45,
"hour_use": 1
}

{
"network_type": "fix",
"average_bit_usage_per_second": 45,
"hour_use": 1,
"nb_users_per_line": 4,
"nb_user_in_usage": 2
}

+ :

• Quite detailed components of the network
• Marginal approach, taking in consideration fix and variable impacts.

- :

• Only usage is measured
• Data to apply the model for a specific service will be hard to gather. Maldmodin's data don't apply to all location/services.
• The allocation of "unused" or "under used" fix power (when the network is not used 100% of the time) is not considered (on-purpuse)

Alternatives

• 1 bytes model

Additional context or elements

The power model seems best suited to represent the impact of fix and mobile network. Using Maldmodin's power factor at first could push stakeholders to challenge those data and create more specific factors.

How could we account for manufacture impact ?
Since network is always up and power model usage impacts gives a promising allocation principle, I suggest making an estimation of manufacture impact based on usage impact : usage_impact*manufacture_impact_facor. We can check the coherence of manufacture_impact_facor with "ADEME - NEGAOCTET" results

Bug report

• Empty post ({}) on /v1/server/bottom-up throw an error
• Incomplete configuration throw an error
  for example, cpu or ram section is missing
• Empty model or configuration throw an error

Problem

As we did for AWS (https://boavizta.github.io/boaviztapi/Explanations/devices/cloud/) we should be able to retrieve the impacts of AZURE instances.

Solution

The same implementation as AWS instances.

Additional context or elements

We should gather data on AZURE instance's hardware.

Format

Bug description

In component.py

sub['_scope3'] = sub[['core_units', 'die_size_per_core']].apply(lambda x: x[0] * x[1])

throws

raise KeyError(key) from err
KeyError: 0

when

multiple line of cpu.csv are selected and the maximum value have to get selected

Exemple

http:///localhost:5000/v1/component/cpu

{
    "process": 22
}

Problem

Units are not specified in impact responses.

Solution

Add static units object in the verbose

Alternatives

Transform impacts from float to string. Concatenated value and unit.
Example : '30' => "30 kgCO2eq"
Drawback : user need to transform the string back into float if they need to reuse the data

Additional context or elements

Example of units JSON object inside verbose

{
"gwp":"kgCO2eq"
"adp":"kgSbeq."
"pe":"MJ"
}

Bug description

Component route consumes internal components class instead of DTO.
http://api.boavizta.org:5000/docs ⇾ Schemas

• CPU | ComponentCPU
• Case | ComponentCase
• PowerComponent | ComponentPowerComponent
• Disk | ComponentHDD, ComponentSSD

Component* Objects should be internal objects. External object should be DTOs.

Expected behavior

Component route should consume component DTO

Epic

Usage

US

As an external user
I can retrieve the scope2 impact of components
With components usage and characteristics

Component yearly consumption

Resources : https://medium.com/teads-engineering/building-an-aws-ec2-carbon-emissions-dataset-3f0fd76c98ac#3a7d

Yearly consumption CPU

yearly_electrical_consumption = (tdp * tdp_ratio * (1-idle_time_ratio) + tdp_idle * idle_time_ratio) * 24 * 365

Yearly consumption of CPU is measure as a ratio of TDP value.
The tdp_ratio can be retrieved in the API data with the medium workload and the CPU model or family.
The TDP can be retrieved in the API data with the CPU model or family.
The ratio and the TDP can be given by the user.

TDP : TDP stands for Thermal Design Power, in watts, and refers to the power consumption under the maximum theoretical load.

Yearly consumption for SSD

TODO

Yearly consumption for RAM

TODO

Yearly consumption for HDD

TODO

Yearly consumption for other

TODO

Problem

When user send a configuration, the way they write strings can vary a little (case, space, …). Strings are often used as an index. If we want the user to have some flexibility, index matching should be non-strict (fuzzy).

Example

Skylake is a cpu family

Request :

"cpu":{
    "core_units":8,
    "cpu_family":"Skylake"
}

But it could be written in different ways : skylake, Skylak, sky lake . We need all of those to match Skylake index.

Solution

Replace strict string matching to fuzzy matching in boaviztapi/model/component for CPU, RAM and SSD in smart_complete.

Epic

ALL

Route(s) involved

/v1/server/bottom_up
/v1/server/

Description

Today the impact factor are stored in a dictionnarry :
https://github.com/Boavizta/Tools-API/blob/main/api/service/server_impact/bottom_up/impact_factor.py

The objectif is to externalize the impact factor on a database (SQL or noSQL ?). This will help supporting the versionning of factors.

TODO

• Create database
• Create impact factor interface
• Change the reference to the dictionnary to the interface

Bug description

Sending a request with incomplete data leads to a 500 error. Like :

INFO:     172.17.0.1:45700 - "POST /v1/component/cpu HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  File "/usr/local/lib/python3.7/site-packages/uvicorn/protocols/http/h11_impl.py", line 366, in run_asgi
    result = await app(self.scope, self.receive, self.send)
  File "/usr/local/lib/python3.7/site-packages/uvicorn/middleware/proxy_headers.py", line 75, in __call__
    return await self.app(scope, receive, send)
  File "/usr/local/lib/python3.7/site-packages/fastapi/applications.py", line 261, in __call__
    await super().__call__(scope, receive, send)
  File "/usr/local/lib/python3.7/site-packages/starlette/applications.py", line 112, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/usr/local/lib/python3.7/site-packages/starlette/middleware/errors.py", line 181, in __call__
    raise exc
  File "/usr/local/lib/python3.7/site-packages/starlette/middleware/errors.py", line 159, in __call__
    await self.app(scope, receive, _send)
  File "/usr/local/lib/python3.7/site-packages/starlette/exceptions.py", line 82, in __call__
    raise exc
  File "/usr/local/lib/python3.7/site-packages/starlette/exceptions.py", line 71, in __call__
    await self.app(scope, receive, sender)
  File "/usr/local/lib/python3.7/site-packages/fastapi/middleware/asyncexitstack.py", line 21, in __call__
    raise e
  File "/usr/local/lib/python3.7/site-packages/fastapi/middleware/asyncexitstack.py", line 18, in __call__
    await self.app(scope, receive, send)
  File "/usr/local/lib/python3.7/site-packages/starlette/routing.py", line 656, in __call__
    await route.handle(scope, receive, send)
  File "/usr/local/lib/python3.7/site-packages/starlette/routing.py", line 259, in handle
    await self.app(scope, receive, send)
  File "/usr/local/lib/python3.7/site-packages/starlette/routing.py", line 61, in app
    response = await func(request)
  File "/usr/local/lib/python3.7/site-packages/fastapi/routing.py", line 228, in app
    dependant=dependant, values=values, is_coroutine=is_coroutine
  File "/usr/local/lib/python3.7/site-packages/fastapi/routing.py", line 160, in run_endpoint_function
    return await dependant.call(**values)
  File "/usr/local/lib/python3.7/site-packages/boaviztapi/routers/component_router.py", line 28, in cpu_impact_bottom_up
    "verbose": verbose_component(completed_cpu, component_cpu, units=cpu.units or 1)}
  File "/usr/local/lib/python3.7/site-packages/boaviztapi/service/verbose.py", line 78, in verbose_component
    "value": rd.round_to_sigfig(*complete_component.impact_gwp()),
  File "/usr/local/lib/python3.7/site-packages/boaviztapi/model/components/component.py", line 85, in impact_gwp
    significant_figures=rd.min_significant_figures(self.die_size_per_core,core_impact,cpu_die_impact,cpu_impact)
  File "/usr/local/lib/python3.7/site-packages/boaviztapi/utils/roundit.py", line 20, in min_significant_figures
    sigfig = significant_number(inputs[0])
  File "/usr/local/lib/python3.7/site-packages/boaviztapi/utils/roundit.py", line 10, in significant_number
    int_part = int(abs(x))
TypeError: bad operand type for abs(): 'NoneType'

To Reproduce

Ask for CPU impact with those data :

"units": 1,
"core_units": 24,
"family": "Skylake",
"manufacture_date": "2017",

Add :
"die_size_per_core": 2.0

Then you get a valid answer.

Expected behavior

Sending an incomplete requests returns a 2xx with a message field that explains why there is no data to return or unsatisfying data.

Additional context

Trying the API through the server agent bootstrapped during hackathon # 4, but this is probably not relevant here.

Problem

Some CPU reference in https://github.com/Boavizta/boaviztapi/blob/main/boaviztapi/data/components/cpu_manufacture.csv has no die_size value nor year. Default value are used.

Solution

Finding die_size for the following CPU type :

Epic

Server

US

As an external user
I can retrieve the impact of a component
With the bottom-up methodology of Boavizta

Route(s) involved

/v1/component/[component]

Process

• The user send data concerning the component (see components documentation.)
• If all the data needed to apply the methodology has been given by the user, the impact is calculated and sent back to the user.
• If not, smart complete #6 is used

Bug description

GWP manufacturing impact is 67 for 2 RAM sticks, but verbose shows 33 for 1 RAM stick.

{'impacts': {'adp': {'manufacture': 0.005,
                     'unit': 'kgSbeq',
                     'use': 'not implemented'},
             'gwp': {'manufacture': 67.0,
                     'unit': 'kgCO2eq',
                     'use': 'not implemented'},
             'pe': {'manufacture': 850.0,
                    'unit': 'MJ',
                    'use': 'not implemented'}},
 'verbose': {'capacity': {'input_value': 8,
                          'status': 'UNCHANGED',
                          'used_value': 8},
             'density': {'input_value': None,
                         'status': 'SET',
                         'used_value': 0.625},
             'impacts': {'adp': {'unit': 'kgSbeq', 'value': 0.0025},
                         'gwp': {'unit': 'kgCO2eq', 'value': 33.0},
                         'pe': {'unit': 'MJ', 'value': 420.0}},
             'manufacturer': {'input_value': 'Hynix/Hyundai',
                              'status': 'UNCHANGED',
                              'used_value': 'Hynix/Hyundai'},
             'model': {'input_value': 'HMT41GS6MFR8C-PB',
                       'status': 'UNCHANGED',
                       'used_value': 'HMT41GS6MFR8C-PB'},
             'units': 2}}

To Reproduce

Send this request :

{'capacity': 8,
 'manufacturer': 'Hynix/Hyundai',
 'model': 'HMT41GS6MFR8C-PB',
 'units': 2}

Expected behavior

Final impact of 2 ram sticks is equal to 2x (impact of 1 ram stick).

Problem

It seems that changes in documentation are not automatically reflected on http://api.boavizta.org/.

Solution

Automate the republish of documentation after a merge to main branch.
Maybe add a github action to handle it.

Problem

1. Users might have multiple server to assess in CSV format. Having a little script to translate CSV into JSON POST request would help some users.

2. When creating multiple archetype, having a CSV to fill is much easier. Having a little script to translate CSV into JSON archetype would avoid manual conversion.

Solution

A script converting CSV to JSON server for each CSV line.

Additional context or elements

@bertrandkeller I think you have done a very similar work. It could be very easy to implement with a generalization of your work if you're ok to share ?

Problem

Impacts can't be chosen in a request - all impacts are returned.

Solution

Add a query parameter in each route containing a list of impacts name.

['gwp', 'pe', 'adp']

In bottom-up service return only the impact in the dataset.

Additional context or elements

The following impacts can be retrieved :

Epic

Usage

US

As an external user
I can retrieve the scope2 impact of devices
With device usage and characteristics

Usage object

• The Usage object is the default component describing the usage and impacts of devices

usage attributes

{
"max_power": float,
"yearly_electrical_consumption": float
"life_duration": int,
"usage_location": string,
"idle_time_ratio": float,
"workload_ratio": float,
"carbon_intensity": float,
"adp_factor": float
}

Yearly electrical consumption

yearly_electrical_consumption is given by the user or smart complete depending on the type of component or device (see below)

GWP

• The GWP impact is measured with the carbon intensity factor depending on the location of the device (country mean)
• The user can give its own carbon intensity in case it has been provided by his own electricity provider, for example

gwp = yearly_electrical_consumption*life_duration*carbon_intensity_factor

PE

• The PE impact is measured with the primary emission factor depending on the location of the device (country mean)
• The user can give its own primary emission factor in case it has been provided by his own electricity provider, for example

pe = (yearly_electrical_consumption*life_duration) * primary_energy_factor

ADP

adp = (yearly_electrical_consumption*life_duration) * abiotic_depletion_potential_factor

Description

TODO

Example

route

Bottom-up methodology : POST 149.202.185.115:5000/v1/server/bottom-up

Input

{
    "model":
    {
        "type": "rack",
        "year": 2020
    },
    "configuration":
    {
        "cpu":
        {
            "units": 2,
            "core_units": 24,
            "family": "Skylake"
        },
        "ram":
        [
            {
                "units": 12,
                "capacity": 32,
                "manufacturer": "Samsung"
            }
        ],
        "disk":
        [
            {
                "units": 1,
                "type": "ssd",
                "capacity": 400,
                "manufacturer": "Samsung"
            }
        ],
        "power_supply":
        {
            "units": 2
        }
    }
}

Output exemple

{
    "gwp": 1853.0,
    "pe": 23857.0,
    "adp": 0.174
}

Bug description

In the main documentation, the link to Boavizta server impact measurement methodology returns 404 not found.

To Reproduce

1. Open dev documentation server
2. Go to section Docs » Introduction » Usefull ressources http://149.202.185.115/introduction/usefull_ressources/
3. Click on Boavizta server impact measurement methodology https://boavizta.cmakers.io/blog/numerique-et-environnement-comment-evaluer-l-empreinte-de-la-fabrication-d-un-serveur-au-dela-des-emissions-de-gaz-a-effet-de-se?token=2112aecb183b1b5d27e137abc61e0f0d39fabf99
4. Error 404

Expected behavior

Open the following URL instead: https://boavizta.cmakers.io/blog/empreinte-de-la-fabrication-d-un-serveur

Problem

No GPU components are implemented. It makes it to impossible to evaluate high performance compute server. Some services cannot be assessed :

• IA
• Cryptomining
• High performance computing.

Solution

We need resources on scope 3 impacts of GPUs. Are GPUs manufacture impacts depend on their die size ?

Additional context or elements

Linked with this issue : Boavizta/environmental-footprint-data#50

Epic

Server

US

As an external user
I can obtain the hypothesis used to measure the impact of my server
When I make a call for a measure

Conditions

• For each component
• For each list of components (i.e. devices)
• When verbose is set at true
• verbose is true on by default

Process

• The impacts of each component in the device is given in the verbose object
• The input value given by the user for each component attribute given or smart completed
• The input value used by the API for each component attribute given or smart completed
• The status of the attribute
  - UNCHANGED : the attribute given by the user have not been modified
  - SET: the user has given no value for the attribute, but the API have set a value of the attribute
  - MODIFY: the user has given no value for the attribute, but the API have modify the value of the attribute

Epic

ALL

Route(s) involved

ALL
...

Description

The impacts data model describes the impacts of an equipment

Example

Impacts

{
    "gwp": 969.8023516103958,
    "pe": 12896.469589529004,
    "adp": 0.1491889078742977
}

Problem

As dicussed in #51 we could update the name of several sections of documentation.

Solution

Apply the following:

1. rename "FUNCTIONAL" by explanation. I like the fact that there is 0 code nor API request in this section. It's a way to explain our methodology for non developers.
2. rename "HOW TO" by reference
3. Create a real "HOW TO" section with real explainable use cases
4. Today, "TRY IT OUT" is a more condensed documentation than a proper tutorial. We could keep "TRY IT OUT" as an executable steel cheat and create a quick tutorial to fulfill all the goals you have presented.

Also:

5. group Home and Introduction as a single topic that provides links to other sections.
6. Move the useffull resources to the reference section.

Epic

Server

US

As an external user
I can retrieve the impact of my server
With the best Boavizta data/methodology

Route(s) involved

/v1/server

Process

• If the model is given, returns the impact with ref data (#1)

• If the model is given but ref data (#1) returns nothing, use bottom-up methodology (#6)

• If the configuration and the model are given return the use bottom-up methodology (#6) -TO VALIDATE-