diff --git a/caimira/docs/mkdocs/docs/code/rest_api.md b/caimira/docs/mkdocs/docs/code/rest_api.md index 929a9ed0..8fc583b4 100644 --- a/caimira/docs/mkdocs/docs/code/rest_api.md +++ b/caimira/docs/mkdocs/docs/code/rest_api.md @@ -62,12 +62,20 @@ To run the API, follow these steps from the root directory of the project: The web server will be accessible at [http://localhost:8081/](http://localhost:8081/). -#### API Endpoints +### API Endpoints -As the project is growing, more endpoints targeted to specific tasks will be developed. +Currently, the REST API contains two routing categories that provide the generation of results for the main CAiMIRA outputs: -??? "POST **/virus_report** (virus report data generation)" +- [Virus results](#virus-results) +- [CO₂ results](#co2-results) +!!! note + As the project is growing, more routes targeted to specific tasks will be developed. + +#### Virus Results + +??? Abstract "POST **/virus/report** (virus report data generation):" + * **Description**: Core endpoint that allows users to submit data for the virus report generation. Data is processed by the CAiMIRA engine, and the results are returned in the response. * **Input**: The body of the request must include the necessary input data in JSON format. Examples of the required input can be found [here](https://gitlab.cern.ch/caimira/caimira/-/blob/master/caimira/src/caimira/calculator/validators/defaults.py?ref_type=heads). * **Response**: On success (status code `200`), the response will contain the following structure: @@ -75,137 +83,184 @@ As the project is growing, more endpoints targeted to specific tasks will be dev { "status": "success", "message": "Results generated successfully", - "report_data": { + "results": { ... } } * **Error Handling**: In case of errors, the API will return appropriate error messages and HTTP status codes, such as `400` for bad requests, `404` for not found, or `500` for internal server errors. - **Example body**: - - { - "activity_type": "office", - "calculator_version": "N/A", - "event_month": "January", - "exposed_finish": "18:00", - "exposed_lunch_finish": "13:30", - "exposed_lunch_start": "12:30", - "exposed_start": "09:00", - "infected_finish": "18:00", - "infected_lunch_finish": "13:30", - "infected_lunch_start": "12:30", - "infected_people": "1", - "infected_start": "09:00", - "inside_temp": "293.", - "location_latitude": 46.20833, - "location_longitude": 6.14275, - "location_name": "Geneva", - "opening_distance": "0.2", - "room_number": "123", - "room_volume": "75", - "simulation_name": "Test", - "total_people": "10", - "ventilation_type": "natural_ventilation", - "virus_type": "SARS_CoV_2_OMICRON", - "volume_type": "room_volume_explicit", - "window_height": "2", - "window_opening_regime": "windows_open_permanently", - "window_type": "window_sliding", - "window_width": "2", - "windows_duration": "10", - "windows_frequency": "60", - "windows_number": "1" - } + ??? note "Example body" + { + "activity_type": "office", + "calculator_version": "N/A", + "event_month": "January", + "exposed_finish": "18:00", + "exposed_lunch_finish": "13:30", + "exposed_lunch_start": "12:30", + "exposed_start": "09:00", + "infected_finish": "18:00", + "infected_lunch_finish": "13:30", + "infected_lunch_start": "12:30", + "infected_people": "1", + "infected_start": "09:00", + "inside_temp": "293.", + "location_latitude": 46.20833, + "location_longitude": 6.14275, + "location_name": "Geneva", + "opening_distance": "0.2", + "room_number": "123", + "room_volume": "75", + "simulation_name": "Test", + "total_people": "10", + "ventilation_type": "natural_ventilation", + "virus_type": "SARS_CoV_2_OMICRON", + "volume_type": "room_volume_explicit", + "window_height": "2", + "window_opening_regime": "windows_open_permanently", + "window_type": "window_sliding", + "window_width": "2", + "windows_duration": "10", + "windows_frequency": "60", + "windows_number": "1" + } For the full list of accepted inputs and respective values please refer to CAiMIRA's official defaults in GitLab repository [here](https://gitlab.cern.ch/caimira/caimira/-/blob/master/caimira/src/caimira/calculator/validators/co2/co2_validator.py?ref_type=heads#L29). ??? note "Example cURL (with the above body)" - curl -X POST "http://localhost:8081/virus_report" \ + curl -X POST "http://localhost:8081/virus/report" \ -H "Content-Type: application/json" \ -d '{ - "activity_type": "office", - "calculator_version": "N/A", - "event_month": "January", - "exposed_finish": "18:00", - "exposed_lunch_finish": "13:30", - "exposed_lunch_start": "12:30", - "exposed_start": "09:00", - "infected_finish": "18:00", - "infected_lunch_finish": "13:30", - "infected_lunch_start": "12:30", - "infected_people": "1", - "infected_start": "09:00", - "inside_temp": "293.", - "location_latitude": 46.20833, - "location_longitude": 6.14275, - "location_name": "Geneva", - "opening_distance": "0.2", - "room_number": "123", - "room_volume": "75", - "simulation_name": "Test", - "total_people": "10", - "ventilation_type": "natural_ventilation", - "virus_type": "SARS_CoV_2_OMICRON", - "volume_type": "room_volume_explicit", - "window_height": "2", - "window_opening_regime": "windows_open_permanently", - "window_type": "window_sliding", - "window_width": "2", - "windows_duration": "10", - "windows_frequency": "60", - "windows_number": "1" + "activity_type": "office", + "calculator_version": "N/A", + "event_month": "January", + "exposed_finish": "18:00", + "exposed_lunch_finish": "13:30", + "exposed_lunch_start": "12:30", + "exposed_start": "09:00", + "infected_finish": "18:00", + "infected_lunch_finish": "13:30", + "infected_lunch_start": "12:30", + "infected_people": "1", + "infected_start": "09:00", + "inside_temp": "293.", + "location_latitude": 46.20833, + "location_longitude": 6.14275, + "location_name": "Geneva", + "opening_distance": "0.2", + "room_number": "123", + "room_volume": "75", + "simulation_name": "Test", + "total_people": "10", + "ventilation_type": "natural_ventilation", + "virus_type": "SARS_CoV_2_OMICRON", + "volume_type": "room_volume_explicit", + "window_height": "2", + "window_opening_regime": "windows_open_permanently", + "window_type": "window_sliding", + "window_width": "2", + "windows_duration": "10", + "windows_frequency": "60", + "windows_number": "1" }' **Note**: The `report_generation_parallelism` can be passed as an argument with integer values. If omitted, `None` will be considered by default. -??? "POST **/co2_report** (CO2 report data generation)" +#### CO₂ Results + +??? Abstract "POST **/co2/transition_times** (suggested ventilation transition times)" - * **Description**: Core endpoint that allows users to submit data for the CO2 report generation. Data is processed by the CAiMIRA engine, and the results are returned in the response. - * The input, response and error handling topics are similar to the previously described `virus_report` section. + * **Description**: Endpoint that allows users to retrieve the suggested ventilation times based on the CO₂ input data. Data is processed by the CAiMIRA engine, and the results are returned in the response. - **Example body:** + ??? note "Example body" - { - "CO2_data": "{\"times\":[8,8,8.1,8.1,8.1,8.2,8.2,8.2,8.3,8.3,8.3,8.4,8.4,8.4,8.5,8.5,8.5,8.6,8.6,8.6,8.7,8.7,8.7,8.8,8.8,8.8,8.9,8.9,8.9,9,9,9,9.1,9.1,9.1,9.2,9.2,9.2,9.3,9.3,9.3,9.4,9.4,9.4,9.5,9.5,9.5,9.6,9.6,9.6,9.7,9.7,9.7,9.8,9.8,9.8,9.9,9.9,9.9,10,10,10,10.1,10.1,10.1,10.2,10.2,10.2,10.3,10.3,10.3,10.4,10.4,10.4,10.5,10.5,10.5,10.6,10.6,10.6,10.7,10.7,10.7,10.8,10.8,10.8,10.9,10.9,10.9,11,11,11,11.1,11.1,11.1,11.2,11.2,11.2,11.3,11.3,11.3,11.4,11.4,11.4,11.5,11.5,11.5,11.6,11.6,11.6,11.7,11.7,11.7,11.8,11.8,11.8,11.9,11.9,11.9,12,12,12,12.1,12.1,12.1,12.2,12.2,12.2,12.3,12.3,12.3,12.4,12.4,12.4,12.5,12.5,12.5,12.6,12.6,12.6,12.7,12.7,12.7,12.8,12.8,12.8,12.9,12.9,12.9,13,13,13,13.1,13.1,13.1,13.2,13.2,13.2,13.3,13.3,13.3,13.4,13.4,13.4,13.5,13.5,13.5,13.6,13.6,13.6,13.7,13.7,13.7,13.8,13.8,13.8,13.9,13.9,13.9,14,14,14,14.1,14.1,14.1,14.2,14.2,14.2,14.3,14.3,14.3,14.4,14.4,14.4,14.5,14.5,14.5,14.6,14.6,14.6,14.7,14.7,14.7,14.8,14.8,14.8,14.9,14.9,14.9,15,15,15,15.1,15.1,15.1,15.2,15.2,15.2,15.3,15.3,15.3,15.4,15.4,15.4,15.5,15.5,15.5,15.6,15.6,15.6,15.7,15.7,15.7,15.8,15.8,15.8,15.9,15.9,15.9,16,16,16,16.1,16.1,16.1,16.2,16.2,16.2,16.3,16.3,16.3,16.4,16.4,16.4,16.5,16.5,16.5,16.6,16.6,16.6,16.7,16.7,16.7,16.8,16.8,16.8,16.9,16.9,16.9,17,17,17,17.1,17.1,17.1,17.2,17.2,17.2,17.3,17.3,17.3,17.4,17.4,17.4,17.5,17.5,17.5,17.6,17.6,17.6,17.7,17.7,17.7,17.8,17.8,17.8,17.9,17.9,17.9,18,18,18,18.1,18.1,18.1,18.2,18.2,18.2,18.3,18.3,18.3,18.4,18.4,18.4,18.5,18.5,18.5,18.6,18.6,18.6,18.7,18.7,18.7,18.8,18.8,18.8,18.9,18.9,18.9,19,19,19,19.1,19.1,19.1,19.2,19.2,19.2,19.3,19.3,19.3,19.4,19.4,19.4,19.5,19.5,19.5,19.6,19.6,19.6,19.7,19.7,19.7,19.8,19.8,19.8,19.9,19.9,19.9,20],\"CO2\":[445.2,443.3,440.9,443.4,442.4,444.1,445.2,445.7,448,448,444,442.5,439.3,438.2,441.4,441.2,443.8,445.2,446.5,445.3,452.1,458.8,470.8,478.1,488.3,502.1,522.1,545.5,579.9,616.2,641.2,676.3,701.9,720.5,746.9,765.8,779.1,794.2,810.6,826,838.3,854.4,876.4,886.2,898.4,921.7,942.8,953.8,979,990.3,1002.9,1017.4,1029.4,1041,1051.9,1067.2,1073.5,1079.7,1093.7,1104.8,1125.8,1141.1,1151,1160.1,1176.4,1193.7,1180.1,1015.3,864.7,802.7,774.5,728.3,697.3,676.1,657.6,640.6,606.5,595.9,577.8,553.6,530.2,525,523.2,521.5,512.9,505.3,502.1,502.5,505.2,507.5,509.2,511.3,513.8,520.4,529.1,532.8,530.1,524,521.6,519.1,510.3,510,514.3,518.4,524.6,521,519.4,523.3,527.5,528.3,526.4,527,530,534,535.6,533.5,530.6,522.3,524.2,532,539.1,538.8,526.2,517.5,508,493.7,485.6,479.5,471.6,472.2,468.2,463.1,461,459,456.4,458.6,459.2,463,465.6,468.4,475.2,480.3,489,528,579.6,606.6,611.2,617,635.9,651.1,676.6,696.6,714.6,729.9,744.7,766,788.5,812.1,832.8,854.7,883.9,895.6,910,924.4,944.5,956.8,971.4,981.3,993.6,1004.4,1021.6,1035.2,1043.8,1063.7,1071,1065.6,1065.9,1073.7,1086.4,1093.5,1120.1,1189.3,1202.9,1218.6,1238.5,1250.1,1263.5,1265,1270.1,1281.6,1294.9,1304.2,1315.5,1338.4,1351.5,1353.4,1364,1361.7,1343.3,1329.7,1320.4,1310.5,1313.6,1305.5,1313.4,1307.5,1290,1286.9,1289.3,1276.8,1268.9,1266.1,1264,1271.8,1268.5,1244.5,1206.4,1173.6,1145,1157.2,1194.4,1198.3,1196.1,1182.5,1167.9,1150.4,1132.8,1108.1,1097.4,1099.8,1093.4,1086.8,1086.9,1083.8,1075.5,1059.9,1048.4,1047.4,1042.6,1036.1,1026.9,1022.7,1017.6,1023.5,1021,1017.3,1004.6,908.3,906.5,979.2,955.8,928.9,915.3,914.1,930.1,923.3,921,865.9,860.2,867,869.7,871.4,861.5,862.9,850.4,843.9,839.7,838.1,839.8,849.7,841.6,820.8,825,838.5,853.8,855.6,838.7,818.1,811.7,804.3,794.5,790.6,782,788.6,779.6,804.2,836.9,852.4,856.9,858.1,857.9,856.5,856.7,851.7,849.6,849.2,846,846.8,844.8,842,839,836,833.2,832.6,830.9,825.9,823.6,823.7,818.2,812.4,810.2,808.4,806.7,803,800.2,794.3,790.5,790.4,787.7,783.3,780.5,784,780.9,780.8,777.2,775,768.7,763.6,761.5,757.8,760,762.1,761.6,761.2,761.5,757.5,754.5,752.6,752.1,751.7,748.6,744.3,742.1,737.6,731,732.6,726.8,726.2,726.9,727.1,726.8,728.9,729.9,726.5,724.8,723.9,723,721.1,720.2,721.1]}", - "exposed_lunch_finish": "13:30", - "exposed_lunch_start": "12:30", - "exposed_start": "08:30", - "fitting_ventilation_states": "[8.5, 17.5]", - "infected_finish": "17:30", - "infected_lunch_finish": "13:30", - "infected_lunch_start": "12:30", - "infected_people": "1", - "infected_start": "08:30", - "room_capacity": "10", - "room_volume": "60", - "total_people": "2" - } + { + "CO2_data": "{\"times\":[8.000,8.033,8.067,8.100,8.133,8.167,8.200,8.233,8.267,8.300,8.333,8.367,8.400,8.433,8.467,8.500,8.533,8.567,8.600,8.633,8.667,8.700,8.733,8.767,8.800,8.833,8.867,8.900,8.933,8.967,9.000,9.033,9.067,9.100,9.133,9.167,9.200,9.233,9.267,9.300,9.333,9.367,9.400,9.433,9.467,9.500,9.533,9.567,9.600,9.633,9.667,9.700,9.733,9.767,9.800,9.833,9.867,9.900,9.933,9.967,10.000,10.033,10.067,10.100,10.133,10.167,10.200,10.233,10.267,10.300,10.333,10.367,10.400,10.433,10.467,10.500,10.533,10.567,10.600,10.633,10.667,10.700,10.733,10.767,10.800,10.833,10.867,10.900,10.933,10.967,11.000,11.033,11.067,11.100,11.133,11.167,11.200,11.233,11.267,11.300,11.333,11.367,11.400,11.433,11.467,11.500,11.533,11.567,11.600,11.633,11.667,11.700,11.733,11.767,11.800,11.833,11.867,11.900,11.933,11.967,12.000,12.033,12.067,12.100,12.133,12.167,12.200,12.233,12.267,12.300,12.333,12.367,12.400,12.433,12.467,12.500,12.533,12.567,12.600,12.633,12.667,12.700,12.733,12.767,12.800,12.833,12.867,12.900,12.933,12.967,13.001],\"CO2\":[445.189,443.284,440.908,443.431,442.366,444.094,445.152,445.656,447.968,447.998,443.950,442.547,439.313,438.225,441.433,441.190,443.804,445.173,446.494,445.278,452.073,458.844,470.828,478.147,488.338,502.126,522.057,545.519,579.881,616.245,641.154,676.288,701.938,720.464,746.933,765.830,779.098,794.173,810.624,825.967,838.340,854.355,876.382,886.208,898.408,921.718,942.848,953.812,978.956,990.321,1002.931,1017.361,1029.379,1041.028,1051.883,1067.220,1073.530,1079.738,1093.733,1104.814,1125.798,1141.115,1151.046,1160.053,1176.367,1193.665,1180.104,1015.334,864.746,802.681,774.455,728.268,697.326,676.063,657.555,640.564,606.534,595.925,577.753,553.605,530.213,524.968,523.153,521.534,512.944,505.297,502.056,502.463,505.248,507.477,509.171,511.313,513.780,520.393,529.137,532.798,530.111,523.964,521.574,519.052,510.294,509.982,514.349,518.396,524.603,521.003,519.448,523.313,527.460,528.326,526.355,527.008,529.968,534.019,535.616,533.514,530.552,522.348,524.243,532.021,539.127,538.836,526.186,517.509,507.993,493.703,485.632,479.527,471.584,472.226,468.206,463.099,461.038,458.980,456.354,458.615,459.162,462.963,465.558,468.448,475.207,480.323,488.962,527.992,579.613,606.594,611.218,617.023,635.927,651.079,676.647]}", + "total_people":"2", + "exposed_start":"08:30", + "exposed_finish":"13:00", + "infected_start":"08:30", + "infected_finish":"13:00", + "infected_people":"1", + "room_volume":"60", + "room_capacity": 10 + } + + In case of success (`200`), the response will contain the following structure: + + { + "status": "success", + "message": "Results generated successfully", + "results": [ + 8.5, + 10.167, + 12.467, + 13.0 + ] + } For the full list of accepted inputs and respective values please refer to CAiMIRA's official defaults in GitLab repository [here](https://gitlab.cern.ch/caimira/caimira/-/blob/master/caimira/src/caimira/calculator/validators/defaults.py?ref_type=heads). ??? "**Example cURL** (with the above body)" - curl -X POST "http://localhost:8081/co2_report" \ + curl -X POST "http://localhost:8081/co2/transition_times" \ -H "Content-Type: application/json" \ -d '{ - "CO2_data": "{\"times\":[8,8,8.1,8.1,8.1,8.2,8.2,8.2,8.3,8.3,8.3,8.4,8.4,8.4,8.5,8.5,8.5,8.6,8.6,8.6,8.7,8.7,8.7,8.8,8.8,8.8,8.9,8.9,8.9,9,9,9,9.1,9.1,9.1,9.2,9.2,9.2,9.3,9.3,9.3,9.4,9.4,9.4,9.5,9.5,9.5,9.6,9.6,9.6,9.7,9.7,9.7,9.8,9.8,9.8,9.9,9.9,9.9,10,10,10,10.1,10.1,10.1,10.2,10.2,10.2,10.3,10.3,10.3,10.4,10.4,10.4,10.5,10.5,10.5,10.6,10.6,10.6,10.7,10.7,10.7,10.8,10.8,10.8,10.9,10.9,10.9,11,11,11,11.1,11.1,11.1,11.2,11.2,11.2,11.3,11.3,11.3,11.4,11.4,11.4,11.5,11.5,11.5,11.6,11.6,11.6,11.7,11.7,11.7,11.8,11.8,11.8,11.9,11.9,11.9,12,12,12,12.1,12.1,12.1,12.2,12.2,12.2,12.3,12.3,12.3,12.4,12.4,12.4,12.5,12.5,12.5,12.6,12.6,12.6,12.7,12.7,12.7,12.8,12.8,12.8,12.9,12.9,12.9,13,13,13,13.1,13.1,13.1,13.2,13.2,13.2,13.3,13.3,13.3,13.4,13.4,13.4,13.5,13.5,13.5,13.6,13.6,13.6,13.7,13.7,13.7,13.8,13.8,13.8,13.9,13.9,13.9,14,14,14,14.1,14.1,14.1,14.2,14.2,14.2,14.3,14.3,14.3,14.4,14.4,14.4,14.5,14.5,14.5,14.6,14.6,14.6,14.7,14.7,14.7,14.8,14.8,14.8,14.9,14.9,14.9,15,15,15,15.1,15.1,15.1,15.2,15.2,15.2,15.3,15.3,15.3,15.4,15.4,15.4,15.5,15.5,15.5,15.6,15.6,15.6,15.7,15.7,15.7,15.8,15.8,15.8,15.9,15.9,15.9,16,16,16,16.1,16.1,16.1,16.2,16.2,16.2,16.3,16.3,16.3,16.4,16.4,16.4,16.5,16.5,16.5,16.6,16.6,16.6,16.7,16.7,16.7,16.8,16.8,16.8,16.9,16.9,16.9,17,17,17,17.1,17.1,17.1,17.2,17.2,17.2,17.3,17.3,17.3,17.4,17.4,17.4,17.5,17.5,17.5,17.6,17.6,17.6,17.7,17.7,17.7,17.8,17.8,17.8,17.9,17.9,17.9,18,18,18,18.1,18.1,18.1,18.2,18.2,18.2,18.3,18.3,18.3,18.4,18.4,18.4,18.5,18.5,18.5,18.6,18.6,18.6,18.7,18.7,18.7,18.8,18.8,18.8,18.9,18.9,18.9,19,19,19,19.1,19.1,19.1,19.2,19.2,19.2,19.3,19.3,19.3,19.4,19.4,19.4,19.5,19.5,19.5,19.6,19.6,19.6,19.7,19.7,19.7,19.8,19.8,19.8,19.9,19.9,19.9,20],\"CO2\":[445.2,443.3,440.9,443.4,442.4,444.1,445.2,445.7,448,448,444,442.5,439.3,438.2,441.4,441.2,443.8,445.2,446.5,445.3,452.1,458.8,470.8,478.1,488.3,502.1,522.1,545.5,579.9,616.2,641.2,676.3,701.9,720.5,746.9,765.8,779.1,794.2,810.6,826,838.3,854.4,876.4,886.2,898.4,921.7,942.8,953.8,979,990.3,1002.9,1017.4,1029.4,1041,1051.9,1067.2,1073.5,1079.7,1093.7,1104.8,1125.8,1141.1,1151,1160.1,1176.4,1193.7,1180.1,1015.3,864.7,802.7,774.5,728.3,697.3,676.1,657.6,640.6,606.5,595.9,577.8,553.6,530.2,525,523.2,521.5,512.9,505.3,502.1,502.5,505.2,507.5,509.2,511.3,513.8,520.4,529.1,532.8,530.1,524,521.6,519.1,510.3,510,514.3,518.4,524.6,521,519.4,523.3,527.5,528.3,526.4,527,530,534,535.6,533.5,530.6,522.3,524.2,532,539.1,538.8,526.2,517.5,508,493.7,485.6,479.5,471.6,472.2,468.2,463.1,461,459,456.4,458.6,459.2,463,465.6,468.4,475.2,480.3,489,528,579.6,606.6,611.2,617,635.9,651.1,676.6,696.6,714.6,729.9,744.7,766,788.5,812.1,832.8,854.7,883.9,895.6,910,924.4,944.5,956.8,971.4,981.3,993.6,1004.4,1021.6,1035.2,1043.8,1063.7,1071,1065.6,1065.9,1073.7,1086.4,1093.5,1120.1,1189.3,1202.9,1218.6,1238.5,1250.1,1263.5,1265,1270.1,1281.6,1294.9,1304.2,1315.5,1338.4,1351.5,1353.4,1364,1361.7,1343.3,1329.7,1320.4,1310.5,1313.6,1305.5,1313.4,1307.5,1290,1286.9,1289.3,1276.8,1268.9,1266.1,1264,1271.8,1268.5,1244.5,1206.4,1173.6,1145,1157.2,1194.4,1198.3,1196.1,1182.5,1167.9,1150.4,1132.8,1108.1,1097.4,1099.8,1093.4,1086.8,1086.9,1083.8,1075.5,1059.9,1048.4,1047.4,1042.6,1036.1,1026.9,1022.7,1017.6,1023.5,1021,1017.3,1004.6,908.3,906.5,979.2,955.8,928.9,915.3,914.1,930.1,923.3,921,865.9,860.2,867,869.7,871.4,861.5,862.9,850.4,843.9,839.7,838.1,839.8,849.7,841.6,820.8,825,838.5,853.8,855.6,838.7,818.1,811.7,804.3,794.5,790.6,782,788.6,779.6,804.2,836.9,852.4,856.9,858.1,857.9,856.5,856.7,851.7,849.6,849.2,846,846.8,844.8,842,839,836,833.2,832.6,830.9,825.9,823.6,823.7,818.2,812.4,810.2,808.4,806.7,803,800.2,794.3,790.5,790.4,787.7,783.3,780.5,784,780.9,780.8,777.2,775,768.7,763.6,761.5,757.8,760,762.1,761.6,761.2,761.5,757.5,754.5,752.6,752.1,751.7,748.6,744.3,742.1,737.6,731,732.6,726.8,726.2,726.9,727.1,726.8,728.9,729.9,726.5,724.8,723.9,723,721.1,720.2,721.1]}", - "exposed_lunch_finish": "13:30", - "exposed_lunch_start": "12:30", - "exposed_start": "08:30", - "fitting_ventilation_states": "[8.5, 17.5]", - "infected_finish": "17:30", - "infected_lunch_finish": "13:30", - "infected_lunch_start": "12:30", - "infected_people": "1", - "infected_start": "08:30", - "room_capacity": "10", - "room_volume": "60", - "total_people": "2" + "CO2_data": "{\"times\":[8.000,8.033,8.067,8.100,8.133,8.167,8.200,8.233,8.267,8.300,8.333,8.367,8.400,8.433,8.467,8.500,8.533,8.567,8.600,8.633,8.667,8.700,8.733,8.767,8.800,8.833,8.867,8.900,8.933,8.967,9.000,9.033,9.067,9.100,9.133,9.167,9.200,9.233,9.267,9.300,9.333,9.367,9.400,9.433,9.467,9.500,9.533,9.567,9.600,9.633,9.667,9.700,9.733,9.767,9.800,9.833,9.867,9.900,9.933,9.967,10.000,10.033,10.067,10.100,10.133,10.167,10.200,10.233,10.267,10.300,10.333,10.367,10.400,10.433,10.467,10.500,10.533,10.567,10.600,10.633,10.667,10.700,10.733,10.767,10.800,10.833,10.867,10.900,10.933,10.967,11.000,11.033,11.067,11.100,11.133,11.167,11.200,11.233,11.267,11.300,11.333,11.367,11.400,11.433,11.467,11.500,11.533,11.567,11.600,11.633,11.667,11.700,11.733,11.767,11.800,11.833,11.867,11.900,11.933,11.967,12.000,12.033,12.067,12.100,12.133,12.167,12.200,12.233,12.267,12.300,12.333,12.367,12.400,12.433,12.467,12.500,12.533,12.567,12.600,12.633,12.667,12.700,12.733,12.767,12.800,12.833,12.867,12.900,12.933,12.967,13.001],\"CO2\":[445.189,443.284,440.908,443.431,442.366,444.094,445.152,445.656,447.968,447.998,443.950,442.547,439.313,438.225,441.433,441.190,443.804,445.173,446.494,445.278,452.073,458.844,470.828,478.147,488.338,502.126,522.057,545.519,579.881,616.245,641.154,676.288,701.938,720.464,746.933,765.830,779.098,794.173,810.624,825.967,838.340,854.355,876.382,886.208,898.408,921.718,942.848,953.812,978.956,990.321,1002.931,1017.361,1029.379,1041.028,1051.883,1067.220,1073.530,1079.738,1093.733,1104.814,1125.798,1141.115,1151.046,1160.053,1176.367,1193.665,1180.104,1015.334,864.746,802.681,774.455,728.268,697.326,676.063,657.555,640.564,606.534,595.925,577.753,553.605,530.213,524.968,523.153,521.534,512.944,505.297,502.056,502.463,505.248,507.477,509.171,511.313,513.780,520.393,529.137,532.798,530.111,523.964,521.574,519.052,510.294,509.982,514.349,518.396,524.603,521.003,519.448,523.313,527.460,528.326,526.355,527.008,529.968,534.019,535.616,533.514,530.552,522.348,524.243,532.021,539.127,538.836,526.186,517.509,507.993,493.703,485.632,479.527,471.584,472.226,468.206,463.099,461.038,458.980,456.354,458.615,459.162,462.963,465.558,468.448,475.207,480.323,488.962,527.992,579.613,606.594,611.218,617.023,635.927,651.079,676.647]}", + "total_people":"2", + "exposed_start":"08:30", + "exposed_finish":"13:00", + "infected_start":"08:30", + "infected_finish":"13:00", + "infected_people":"1", + "room_volume":"60", + "room_capacity": 10, }' -#### Development +??? Abstract "POST **/co2/report** (CO₂ report data generation)" + + * **Description**: Core endpoint that allows users to submit data for the CO₂ report generation. Data is processed by the CAiMIRA engine, and the results are returned in the response. + * The input, response and error handling topics are similar to the previously described `virus/report` section. + + ??? note "Example body" + + { + "CO2_data": "{\"times\":[8.000,8.033,8.067,8.100,8.133,8.167,8.200,8.233,8.267,8.300,8.333,8.367,8.400,8.433,8.467,8.500,8.533,8.567,8.600,8.633,8.667,8.700,8.733,8.767,8.800,8.833,8.867,8.900,8.933,8.967,9.000,9.033,9.067,9.100,9.133,9.167,9.200,9.233,9.267,9.300,9.333,9.367,9.400,9.433,9.467,9.500,9.533,9.567,9.600,9.633,9.667,9.700,9.733,9.767,9.800,9.833,9.867,9.900,9.933,9.967,10.000,10.033,10.067,10.100,10.133,10.167,10.200,10.233,10.267,10.300,10.333,10.367,10.400,10.433,10.467,10.500,10.533,10.567,10.600,10.633,10.667,10.700,10.733,10.767,10.800,10.833,10.867,10.900,10.933,10.967,11.000,11.033,11.067,11.100,11.133,11.167,11.200,11.233,11.267,11.300,11.333,11.367,11.400,11.433,11.467,11.500,11.533,11.567,11.600,11.633,11.667,11.700,11.733,11.767,11.800,11.833,11.867,11.900,11.933,11.967,12.000,12.033,12.067,12.100,12.133,12.167,12.200,12.233,12.267,12.300,12.333,12.367,12.400,12.433,12.467,12.500,12.533,12.567,12.600,12.633,12.667,12.700,12.733,12.767,12.800,12.833,12.867,12.900,12.933,12.967,13.001],\"CO2\":[445.189,443.284,440.908,443.431,442.366,444.094,445.152,445.656,447.968,447.998,443.950,442.547,439.313,438.225,441.433,441.190,443.804,445.173,446.494,445.278,452.073,458.844,470.828,478.147,488.338,502.126,522.057,545.519,579.881,616.245,641.154,676.288,701.938,720.464,746.933,765.830,779.098,794.173,810.624,825.967,838.340,854.355,876.382,886.208,898.408,921.718,942.848,953.812,978.956,990.321,1002.931,1017.361,1029.379,1041.028,1051.883,1067.220,1073.530,1079.738,1093.733,1104.814,1125.798,1141.115,1151.046,1160.053,1176.367,1193.665,1180.104,1015.334,864.746,802.681,774.455,728.268,697.326,676.063,657.555,640.564,606.534,595.925,577.753,553.605,530.213,524.968,523.153,521.534,512.944,505.297,502.056,502.463,505.248,507.477,509.171,511.313,513.780,520.393,529.137,532.798,530.111,523.964,521.574,519.052,510.294,509.982,514.349,518.396,524.603,521.003,519.448,523.313,527.460,528.326,526.355,527.008,529.968,534.019,535.616,533.514,530.552,522.348,524.243,532.021,539.127,538.836,526.186,517.509,507.993,493.703,485.632,479.527,471.584,472.226,468.206,463.099,461.038,458.980,456.354,458.615,459.162,462.963,465.558,468.448,475.207,480.323,488.962,527.992,579.613,606.594,611.218,617.023,635.927,651.079,676.647]}", + "total_people":"2", + "exposed_start":"08:30", + "exposed_finish":"13:00", + "infected_start":"08:30", + "infected_finish":"13:00", + "infected_people":"1", + "room_volume":"60", + "room_capacity": 10, + "fitting_ventilation_states":"[8.5,10.167,12.467,13.0]" + } + + !!! note + Given the same input values as in the previous example, note that the `fitting_ventilation_states` are those retrieved by the previous route. + + For the full list of accepted inputs and respective values please refer to CAiMIRA's official defaults in GitLab repository [here](https://gitlab.cern.ch/caimira/caimira/-/blob/master/caimira/src/caimira/calculator/validators/defaults.py?ref_type=heads). + + ??? "**Example cURL** (with the above body)" + + curl -X POST "http://localhost:8081/co2/report" \ + -H "Content-Type: application/json" \ + -d '{ + "CO2_data": "{\"times\":[8.000,8.033,8.067,8.100,8.133,8.167,8.200,8.233,8.267,8.300,8.333,8.367,8.400,8.433,8.467,8.500,8.533,8.567,8.600,8.633,8.667,8.700,8.733,8.767,8.800,8.833,8.867,8.900,8.933,8.967,9.000,9.033,9.067,9.100,9.133,9.167,9.200,9.233,9.267,9.300,9.333,9.367,9.400,9.433,9.467,9.500,9.533,9.567,9.600,9.633,9.667,9.700,9.733,9.767,9.800,9.833,9.867,9.900,9.933,9.967,10.000,10.033,10.067,10.100,10.133,10.167,10.200,10.233,10.267,10.300,10.333,10.367,10.400,10.433,10.467,10.500,10.533,10.567,10.600,10.633,10.667,10.700,10.733,10.767,10.800,10.833,10.867,10.900,10.933,10.967,11.000,11.033,11.067,11.100,11.133,11.167,11.200,11.233,11.267,11.300,11.333,11.367,11.400,11.433,11.467,11.500,11.533,11.567,11.600,11.633,11.667,11.700,11.733,11.767,11.800,11.833,11.867,11.900,11.933,11.967,12.000,12.033,12.067,12.100,12.133,12.167,12.200,12.233,12.267,12.300,12.333,12.367,12.400,12.433,12.467,12.500,12.533,12.567,12.600,12.633,12.667,12.700,12.733,12.767,12.800,12.833,12.867,12.900,12.933,12.967,13.001],\"CO2\":[445.189,443.284,440.908,443.431,442.366,444.094,445.152,445.656,447.968,447.998,443.950,442.547,439.313,438.225,441.433,441.190,443.804,445.173,446.494,445.278,452.073,458.844,470.828,478.147,488.338,502.126,522.057,545.519,579.881,616.245,641.154,676.288,701.938,720.464,746.933,765.830,779.098,794.173,810.624,825.967,838.340,854.355,876.382,886.208,898.408,921.718,942.848,953.812,978.956,990.321,1002.931,1017.361,1029.379,1041.028,1051.883,1067.220,1073.530,1079.738,1093.733,1104.814,1125.798,1141.115,1151.046,1160.053,1176.367,1193.665,1180.104,1015.334,864.746,802.681,774.455,728.268,697.326,676.063,657.555,640.564,606.534,595.925,577.753,553.605,530.213,524.968,523.153,521.534,512.944,505.297,502.056,502.463,505.248,507.477,509.171,511.313,513.780,520.393,529.137,532.798,530.111,523.964,521.574,519.052,510.294,509.982,514.349,518.396,524.603,521.003,519.448,523.313,527.460,528.326,526.355,527.008,529.968,534.019,535.616,533.514,530.552,522.348,524.243,532.021,539.127,538.836,526.186,517.509,507.993,493.703,485.632,479.527,471.584,472.226,468.206,463.099,461.038,458.980,456.354,458.615,459.162,462.963,465.558,468.448,475.207,480.323,488.962,527.992,579.613,606.594,611.218,617.023,635.927,651.079,676.647]}", + "total_people":"2", + "exposed_start":"08:30", + "exposed_finish":"13:00", + "infected_start":"08:30", + "infected_finish":"13:00", + "infected_people":"1", + "room_volume":"60", + "room_capacity": 10, + "fitting_ventilation_states":"[8.5,10.167,12.467,13.0]" + }' + +### Development For testing new releases, use the PyPI Test instance by running the following command (directory independent): diff --git a/caimira/docs/mkdocs/docs/root/installation.md b/caimira/docs/mkdocs/docs/root/installation.md index 2bdc7ef9..a4126eea 100644 --- a/caimira/docs/mkdocs/docs/root/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -284,7 +284,7 @@ CAiMIRA backend includes a REST API for programmatic interaction with its models 2. **Test the API**: - Send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the body. Example request formats can be found in the [Virus Validator Code](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). + Send a `POST` request to `http://localhost:8081/virus/report` with the required inputs in the body. Example request formats can be found in the [Virus Validator Code](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). 3. **Example Response**: A successful response will return data in the following format: @@ -293,7 +293,7 @@ CAiMIRA backend includes a REST API for programmatic interaction with its models { "status": "success", "message": "Results generated successfully", - "report_data": { + "results": { ... }, ... diff --git a/caimira/src/caimira/api/controller/co2_report_controller.py b/caimira/src/caimira/api/controller/co2_report_controller.py index 22db3b48..d6285916 100644 --- a/caimira/src/caimira/api/controller/co2_report_controller.py +++ b/caimira/src/caimira/api/controller/co2_report_controller.py @@ -17,7 +17,28 @@ def generate_report(model: CO2DataModel) -> typing.Dict: return dict(model.CO2_fit_params()) -def submit_CO2_form(form_data: typing.Dict) -> typing.Dict: +def generate_transition_times(CO2model: CO2DataModel, vent_transition_times: list) -> list: + # The entire ventilation changes consider the initial and final occupancy state change + occupancy_transition_times = list(CO2model.occupancy.transition_times) + all_vent_transition_times: list = sorted( + [occupancy_transition_times[0]] + + [occupancy_transition_times[-1]] + + vent_transition_times) + return all_vent_transition_times + + +def request_CO2_transition_times(form_data: typing.Dict) -> list: + data_registry: DataRegistry = DataRegistry() + + form_obj: CO2FormData = generate_form_obj(form_data=form_data, data_registry=data_registry) + CO2model: CO2DataModel = generate_model(form_obj=form_obj) + vent_transition_times: list = form_obj.find_change_points() + all_vent_transition_times: list = generate_transition_times(CO2model, vent_transition_times) + + return all_vent_transition_times + + +def request_CO2_report(form_data: typing.Dict) -> typing.Dict: data_registry: DataRegistry = DataRegistry() form_obj: CO2FormData = generate_form_obj(form_data=form_data, data_registry=data_registry) diff --git a/caimira/src/caimira/api/controller/virus_report_controller.py b/caimira/src/caimira/api/controller/virus_report_controller.py index 0b79a276..4375cc35 100644 --- a/caimira/src/caimira/api/controller/virus_report_controller.py +++ b/caimira/src/caimira/api/controller/virus_report_controller.py @@ -4,7 +4,6 @@ import typing from caimira.calculator.validators.virus.virus_validator import VirusFormData from caimira.calculator.store.data_registry import DataRegistry -from caimira.calculator.models.models import ExposureModel import caimira.calculator.report.virus_report_data as rg diff --git a/caimira/src/caimira/api/routes/report_routes.py b/caimira/src/caimira/api/routes/report_routes.py index 61ae80b6..ac261125 100644 --- a/caimira/src/caimira/api/routes/report_routes.py +++ b/caimira/src/caimira/api/routes/report_routes.py @@ -3,7 +3,7 @@ import traceback import sys from caimira.api.routes.base_handler import BaseRequestHandler from caimira.api.controller.virus_report_controller import submit_virus_form -from caimira.api.controller.co2_report_controller import submit_CO2_form +from caimira.api.controller.co2_report_controller import request_CO2_transition_times, request_CO2_report class VirusReportHandler(BaseRequestHandler): @@ -22,7 +22,25 @@ class VirusReportHandler(BaseRequestHandler): response_data = { "status": "success", "message": "Results generated successfully", - "report_data": report_data, + "results": report_data, + } + + self.write(response_data) + except Exception as e: + traceback.print_exc() + self.write_error(status_code=400, exc_info=sys.exc_info()) + + +class CO2SuggestionsHandler(BaseRequestHandler): + def post(self): + try: + form_data = json.loads(self.request.body) + suggestion_data = request_CO2_transition_times(form_data) + + response_data = { + "status": "success", + "message": "Results generated successfully", + "results": suggestion_data, } self.write(response_data) @@ -35,12 +53,12 @@ class CO2ReportHandler(BaseRequestHandler): def post(self): try: form_data = json.loads(self.request.body) - report_data = submit_CO2_form(form_data) + report_data = request_CO2_report(form_data) response_data = { "status": "success", "message": "Results generated successfully", - "report_data": report_data, + "results": report_data, } self.write(response_data) diff --git a/caimira/src/caimira/api/routes/routes.py b/caimira/src/caimira/api/routes/routes.py index 9334c4f6..76432f2f 100644 --- a/caimira/src/caimira/api/routes/routes.py +++ b/caimira/src/caimira/api/routes/routes.py @@ -1,8 +1,9 @@ from caimira.api.routes.landing_routes import LandingPageHandler -from caimira.api.routes.report_routes import VirusReportHandler, CO2ReportHandler +from caimira.api.routes.report_routes import VirusReportHandler, CO2SuggestionsHandler, CO2ReportHandler routes = [ (r"/", LandingPageHandler), - (r"/co2_report", CO2ReportHandler), - (r"/virus_report", VirusReportHandler), + (r"/co2/transition_times", CO2SuggestionsHandler), + (r"/co2/report", CO2ReportHandler), + (r"/virus/report", VirusReportHandler), ] diff --git a/caimira/src/caimira/calculator/models/models.py b/caimira/src/caimira/calculator/models/models.py index 0cd151dd..8a250907 100644 --- a/caimira/src/caimira/calculator/models/models.py +++ b/caimira/src/caimira/calculator/models/models.py @@ -668,7 +668,7 @@ class Particle: IFrac = 1 - 0.5 * (1 - (1 / (1 + (0.00076*(d**2.8))))) fdep = IFrac * (0.0587 + (0.911/(1 + np.exp(4.77 + 1.485 * np.log(d)))) - + (0.943/(1 + np.exp(0.508 - 2.58 * np.log(d))))) + + (0.943/(1 + np.exp(0.508 - 2.58 * np.log(d))))) # type: ignore return fdep