JBODY Web API

Version 1.0, ©2020 Energy Simulation Solutions Ltd

The IESD-FIALA model was developed in 1998 by Dr Dusan Fiala to predict human thermal responses and the associated thermal sensation in a wide range of environments. The model enables thermal influences on human beings to be analysed for transient and heterogeneous conditions with respect to both environmental influences and varying activity levels. The original computer program of the IESD-FIALA model was written in PASCAL, and compiled to run on Microsoft DOS/WINDOWS® platforms.

Computer simulation of the human thermoregulatory system has been a valuable research tool contributing to a deeper understanding of the principles of human thermoregulation. Besides physiological research, there is a growing interest to predict human physiological and comfort responses also in other disciplines of science and technology.

A mathematical model of human thermoregulation and thermal comfort has been developed at IESD, De Montfort University Leicester, based on more than ten year’s research work. The multi-node, dynamic model incorporates two interacting systems of thermoregulation: the controlling, active system and the controlled passive system.

The passive system (Fiala et al. 1999) is a multi-segmental, multi-layered representation of the human body with spatial subdivisions which includes a detailed representation of the anatomic, thermophysical and thermophysiological properties of the human body. The model accounts for phenomena of human heat transfer that occur inside the body (blood circulation, metabolic heat generation, -conduction, and -accumulation) and at its surface (free and forced surface convection, long- and shortwave radiation, skin moisture -evaporation, -diffusion, and -accumulation).

The active system model (Fiala et al. 2001) simulates responses of the human thermoregulatory system, i.e. suppression (vasoconstriction) and elevation (vasodilatation) of the cutaneous blood flow, sweat moisture excretion and changes in the metabolic heat production by shivering thermogenesis. The active system was developed by means of regression analysis using measured responses obtained from steady and transient exposures to cold stress, cold, moderate, warm and hot stress conditions, and exercise intensities between 0.8 - 10 met.

The simulation system incorporates a dynamic thermal comfort model which predicts human perceptual responses from physiological states of the body. The comfort model has been derived by regression analysis using measured thermal sensation votes obtained from over 2000 male and female subjects.

The thermoregulatory and comfort models have been validated extensively against independent experimental data and showed good agreement with measured regulatory responses, mean and local skin temperatures, internal temperatures and thermal sensation responses for the whole spectrum of environmental conditions investigated and for different personal circumstances (Fiala et al. 2001, 2003).

Scientists and engineers can use the model to study responses of (unacclimatized) humans to a wide range of boundary conditions. The IESD-Fiala model provides a basis for a detailed analysis of the transient and complex inhomogeneous environments found in cars, buildings and other man-made spaces and for the analysis of outdoor weather conditions.

The model has found applications, e.g. in medical engineering to predict the temperature and regulatory responses of anaesthetised patients, in the car industry to predict passengers' responses to the transient and asymmetric boundary conditions found inside car cabins, in meteorology to quantify human physiological and comfort responses to outdoor weather conditions, some military applications, and the thermal comfort analysis of buildings and individual built components.

References:

Fiala D., K.J. Lomas, and M. Stohrer (1999) A computer model of human thermoregulation for a wide range of environmental conditions: The passive system. Journal of Applied Physiology, Vol. 87 (5), pp. 1957-1972.

Fiala D., K.J. Lomas, and M. Stohrer (2001) Computer prediction of human thermoregulatory and temperature responses to a wide range of environmental conditions. International Journal of Biometeorology, Vol. 45, pp. 143-159.

Fiala D., K.J. Lomas, and M. Stohrer (2003) First Principles Modelling of Thermal Sensation Responses in Steady-State and Transient Boundary Conditions. ASHRAE Transactions, Vol. 109 (1), pp.179-186.

Work began in the early 2010s to extend the functionality and customizability of the original Fiala model. We intend to expose as many internal parameters as reasonable and to provide a consistent interface for users to access the model, either as a standalone tool or as a functional library that can be integrated into other simulation tools. The ENSIMS JBODY system is the latest incarnation, with works still on-going.

Features:

• Based on the original IESD-Fiala model
• …

Root Url: https://api.ensims.com/jhdts_web/api

This command is for testing if the service is online and retrieving version info.

• Method: GET
• Url Pattern: /info
• Headers: none
• Body: none

curl https://api.ensims.com/jhdts_web/api/info

• Return:

{
  "Title" : "JHDTS Web API",
  "Description" : "Dynamic Thermal Model of Human Body provided by ENSIMS Ltd.",
  "Major" : 1,
  "Minor" : 0,
  "Revision" : 1,
  "Release" : "beta",
  "Update" : 0,
  "Notice" : "(C) 2017, Energy Simulation Solutions Ltd. All rights reserved."
}

List all experiments held on the server of the current user

• Method: GET
• Url Pattern: /list
• Cookies: JWT session token
• Headers: none
• Body: none

curl -b cookies https://api.ensims.com/jhdts_web/api/list

• Return: a list of experiment IDs

[
    "MyExperiment1",
    "MyExperimett2",
    ...
]

This command submits the configuration of the experiment, requires simulation, and retrieves the most commonly used results

• Method: POST
• Url: /run
• Cookies: JWT session token
• Headers: Set Content-Type to application/json
• Body: {experiment data}

curl -b cookies -H "Content-Type: application/json" -X POST -d '{experiment data}' https://api.ensims.com/jhdts_web/api/run

• Return: {results info}

An example configuration is shown below. More details of each field to follow.

{
  "experimentID" : "MyExperiment1",
  "description" : "This is my first experiment",
  "tags" : null,
  "bcs" : [ {
    "time" : 0,
    "stepChange" : true,
    "ta" : 20.0,
    "rh" : 0.5,
    "va" : 0.05,
    "mrt" : 20.0,
    "met" : 1.0,
    "clothes" : "KSU.cl3",
    "solar" : {
      "solarElevation" : 90.0,
      "solarAzimuth" : 90.0,
      "groudReflectance" : 0.2,
      "bodyElevation" : 90.0,
      "bodyOrientaion" : 90.0,
      "diffuse" : 0.0,
      "direct" : 0.0,
      "exposure" : [
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1]
          ]
    },
    "pos" : 0
  }, {
    "time" : 180,
    "stepChange" : true,
    "ta" : 20.0,
    "rh" : 0.5,
    "va" : 0.05,
    "mrt" : 20.0,
    "met" : 1.0,
    "clothes" : "KSU.cl3",
    "solar" : {
      "solarElevation" : 90.0,
      "solarAzimuth" : 90.0,
      "groudReflectance" : 0.2,
      "bodyElevation" : 90.0,
      "bodyOrientaion" : 90.0,
      "diffuse" : 0.0,
      "direct" : 0.0,
      "exposure" : [
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1],
              [1, 1, 1, 1]
          ]
    },
    "pos" : 0
  } ]
}

Solar mask table

An example configuration is shown below. More details of each field to follow.

{
    "experimentID": "MyExperiment1",
    "description": "This is my first experiment",
    "createdAt": "2017-08-17 10:20:30 GMT",
    "ok": true,
    "bcs": [ {
            "time" : 0,
            "stepChange" : true,
            "ta" : 20.0,
            "rh" : 0.5,
            "va" : 0.05,
            "mrt" : 20.0,
            "met" : 1.0,
            "clothes" : "KSU.cl3",
            "solar" : {
              "solarElevation" : 90.0,
              "solarAzimuth" : 90.0,
              "groudReflectance" : 0.2,
              "bodyElevation" : 90.0,
              "bodyOrientaion" : 90.0,
              "diffuse" : 0.0,
              "direct" : 0.0
            },
            "pos" : 0
        }, {
            "time" : 180,
            "stepChange" : true,
            "ta" : 20.0,
            "rh" : 0.5,
            "va" : 0.05,
            "mrt" : 20.0,
            "met" : 1.0,
            "clothes" : "KSU.cl3",
            "solar" : {
              "solarElevation" : 90.0,
              "solarAzimuth" : 90.0,
              "groudReflectance" : 0.2,
              "bodyElevation" : 90.0,
              "bodyOrientaion" : 90.0,
              "diffuse" : 0.0,
              "direct" : 0.0
            },
            "pos" : 0
        } ],
    "reports": [
        "CmfPrm",
        "GlCalVar",
        "GlResults",
        "TskL&R",
        "Tcore",
        "results",
        "qsk",
        "basal",
        "wblsk",
        "Qsk_.",
        "TRS"
    ],
    "result": [
        {
            "Time": 0,
            "Ta": 29.999999999999993,
            "RH": 39.999999999999986,
            "Va": 0.04999999999999998,
            "MRT": 29.999999999999993,
            "Clo": 2.8543277996251865e-15,
            "Tskm": 34.36991135352967,
            "Thy": 37.00103551767457,
            "Tre": 36.89753685324042,
            "Qm": 87.1305908064696,
            "Esk": 19.13076628762653,
            "SkBF": 100.00000000000003,
            "DTS": 0,
            "PPD": 0
        },
        {
            "Time": 1,
            "Ta": 28.000000000000014,
            "RH": 60.00000000000001,
            "Va": 0.09999999999999996,
            "MRT": 16,
            "Clo": 0.88599190512711,
            "Tskm": 34.300444558097034,
            "Thy": 36.99740015918207,
            "Tre": 36.8963518631244,
            "Qm": 108.90662004782678,
            "Esk": 15.792856058419412,
            "SkBF": 96.25995557847818,
            "DTS": -0.9213639908945768,
            "PPD": 22.928340794723724
        },
        ...
        ...
        ...
        {
            "Time": 180,
            "Ta": 28.000000000000014,
            "RH": 60.00000000000001,
            "Va": 0.09999999999999996,
            "MRT": 16,
            "Clo": 0.9250459840647304,
            "Tskm": 33.56209574716113,
            "Thy": 37.11260935133168,
            "Tre": 37.01470200922007,
            "Qm": 109.56409438354824,
            "Esk": 14.841854305367756,
            "SkBF": 65.8551328316323,
            "DTS": 0.10835497923679382,
            "PPD": 5.243167805395657
        }
    ],
}

Retrieving a list of the available report of this experiment

• Method: GET
• Url: /list/{exp_id}
• Cookies: JWT session token
• Headers: none
• Body: none

curl -b cookies  https://api.ensims.com/jhdts_web/api/list/MyExperiment1

• Return: A list of available reports. Details of the reports will be available in the manual (in development)

[
    "CmfPrm",
    "GlCalVar",
    "GlResults",
    "TskL&R",
    "Tcore",
    "results",
    "qsk"
    "basal",
    "wblsk",
    "Qsk_",
    "TRS",
    ...
]

Retrieving individual data report in JSON format

• Method: GET
• Url: /get/{exp_id}/{report_name}
• Cookies: JWT session token
• Headers: none
• Body: none

curl -b cookies  https://api.ensims.com/jhdts_web/api/get/MyExperiment1/CmfPrm

• Return: Time series of multiple parameters of the requested report in JSON format, e.g.

[
  {
    "Time": 0,
    "Ta": 29.999999999999993,
    "RH": 39.999999999999986,
    "Va": 0.04999999999999998,
    "MRT": 29.999999999999993,
    "Clo": 2.8543277996251865e-15,
    "Tskm": 34.36991135352967,
    "Thy": 37.00103551767457,
    "Tre": 36.89753685324042,
    "Qm": 87.1305908064696,
    "Esk": 19.13076628762653,
    "SkBF": 100.00000000000003,
    "DTS": 0,
    "PPD": 0
  },
  {
    "Time": 1,
    "Ta": 28.000000000000014,
    "RH": 60.00000000000001,
    "Va": 0.09999999999999996,
    "MRT": 16,
    "Clo": 0.88599190512711,
    "Tskm": 34.300444558097034,
    "Thy": 36.99740015918207,
    "Tre": 36.8963518631244,
    "Qm": 108.90662004782678,
    "Esk": 15.792856058419412,
    "SkBF": 96.25995557847818,
    "DTS": -0.9213639908945768,
    "PPD": 22.928340794723724
  },
  ...
  {
    "Time": 4,
    "Ta": 28.000000000000014,
    "RH": 60.00000000000001,
    "Va": 0.09999999999999996,
    "MRT": 16,
    "Clo": 0.8925048732693408,
    "Tskm": 34.17890599881812,
    "Thy": 36.98094778456004,
    "Tre": 36.88865700082858,
    "Qm": 108.87291614012169,
    "Esk": 15.660846913662066,
    "SkBF": 89.66349656273863,
    "DTS": -0.4484063401633448,
    "PPD": 9.195526206909989
  }
]

Retrieve the simulation results table in CSV format as it is generated by the model.

• Method: GET
• Url: /view/{exp_id}/{table_name}
• Cookies: JWT session token
• Headers: none
• Body: none

curl -b cookies https://api.ensims.com/jhdts_web/api/view/MyExperiment1/Tcore

• Return: Tcore.csv

#Core temperatures
#Time, head, face, neck, left shldr, thorax, abdomen, left upper arm, left lower arm, left hand, left upper leg, left lower leg, left foot, right shldr, right upper arm, right lower arm, right hand, right upper leg, right lower leg, right foot
#[min], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C], [?C]
0.0,   37.00, 35.32, 35.37, 36.66, 36.66, 36.90, 35.74, 34.87, 35.88, 36.33, 35.51, 34.24, 36.66, 35.74, 34.87, 35.88, 36.33, 35.51, 34.24, 
1.0,   36.99, 35.32, 35.37, 36.65, 36.65, 36.89, 35.74, 34.88, 35.89, 36.33, 35.51, 34.24, 36.65, 35.74, 34.88, 35.89, 36.33, 35.51, 34.24, 
2.0,   36.99, 35.32, 35.37, 36.64, 36.64, 36.89, 35.74, 34.88, 35.89, 36.33, 35.51, 34.25, 36.64, 35.74, 34.88, 35.89, 36.33, 35.51, 34.25, 
3.0,   36.98, 35.32, 35.38, 36.64, 36.64, 36.89, 35.75, 34.89, 35.89, 36.33, 35.51, 34.26, 36.64, 35.75, 34.89, 35.89, 36.33, 35.51, 34.26, 
...

Retrieve all results in a zip file

• Method: GET
• Url: /download/{exp_id}
• Cookies: JWT session token
• Headers: none
• Body: none

curl -b cookies https://api.ensims.com/jhdts_web/api/download/MyExperiment1

• Return: MyExpeirment1.zip

Delete the experiment from server

• Method: POST
• Url: /delete/{exp_id}
• Headers: api_key={…}, session_key={…}
• Body: none

curl -b cookies -X POST https://api.ensims.com/jhdts_web/api/delete/MyExperiment1

• Return: acknowlegement

{
    "experimentID": "MyExperiment1",
    "description": "Deleted",
    "ok": true
}

Although the model supports defining clothing ensembles from individual garments, the current API allows only selection from the list below.

• briefs_(0.0clo).cl3 - wearing only a pair of briefs 0.0 clo
• shorts+shirt_shsl_(0.4clo).cl3 - briefs, walking shorts (cotton), short-sleeve shirt, ankle-length socks, street shoes 0.4 clo in total
• KSU+sh_(0.6clo).cl3 - briefs, ankle-length socks, street shoes, trousers, long-sleeve shirt, 0.6 clo total
• KSU+sweat1+sh_(0.8clo).cl3 - the above plus light sweater, 0.8 clo total
• KSU+sweat2+sh_(0.9clo).cl3 - KSU plus thick, round neck cardigan, total 0.9 clo
• KSU+jacket+sh_(1.0clo).cl3 - KSU plus suite jacket, 1.0 clo
• KSU+sweat1+jacket+sh_(1.1clo).cl3 - KSU plus light sweater and suit jacket
• winter_outdoor_(1.3clo).cl3 - briefs, ankle-length socks, warm shoes, trousers, short-sleeve cotton undershirt, long-sleeve shirt, warm outdoor jacket, 1.3 clo total
• winter_outdoor+cap+gloves_(1.5clo).cl3 - the above plus knitted cap and knitted gloves, 1.5 clo total

The following report files may be created for each simulation. The actual list of reports that are available to download is provided in the simulation result data.