Action disabled: source

JBODY Web API

Version 1.0, ©2020 Energy Simulation Solutions Ltd


The Original Fiala Model

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.

Diagram of the passive system

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).

Diagram of the active system

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.

Asymetrical radiation

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.

The New Way to Run the Model

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

API Overview

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

Command Method Url Pattern Header Body Return
Get service info GET /info - - {ver info}
List all experiments GET /list api_key, session_key - [list of exp_ids]
Run experiment POST /run api_key, session_key {exp config} {result info}
List available reports GET /list/{exp_id} api_key, session_key - [list of reports]
Get report in JSON GET /get/{exp_id}/{report} api_key, session_key - {report}
Get report in CSV GET /view/{exp_id}/{report} api_key, session_key - .csv
Download all reports in ZIP GET /download/{exp_id} api_key, session_key - .zip
Delete experiment POST /delete/{exp_id} api_key, session_key - {acknowledgement}

API Details

Get service info

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

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",
    ...
]

Run experiment

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
curl -b cookies -H "Content-Type: application/json" -X POST -d '{experiment data}' https://api.ensims.com/jhdts_web/api/run

Experiment configuration

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

Sides
Parts # 0 1 2 3
head 0 ant pst
face 1 ant l.ext r.ext
neck 2 ant pst l.ext r.ext
left shldr 3 one side
thorax 4 ant pst l.inf r.inf
abdomen 5 ant pst l.inf r.inf
left upper arm 6 ant pst inf ext
left lower arm 7 ant pst inf ext
left hand 8 hbk plm
left upper leg 9 ant pst inf ext
left lower leg 10 ant pst inf ext
left foot 11 inst sole
right shldr 12 one side
right upper arm 13 ant pst inf ext
right lower arm 14 ant pst inf ext
right hand 15 hbk plm
right upper leg 16 ant pst inf ext
right lower leg 17 ant pst inf ext
right foot 18 inst sole

Experiment results info

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
        }
    ],
}

List available reports

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",
    ...
]

Get report in JSON

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
  }
]

Get report in CSV

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, 
...

Download all reports in ZIP

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 experiment

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
}

Data desciption

Available Clothing files

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

Reports

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.

Class File name Description Local parameters
Model parameters basal.csv Neutral environmental condition, thermal regulatory set points, and basic body parameters -
fcl.csv Local clothing area factors [/] Yes
Heat transfer coefficients and resistances hc.csv Local surface convective heat transfer coefficients [w/m2/K] Yes
hr.csv Local surface long-wave radiant heat transfer coefficients [w/m2/K] Yes
Rcl.csv Local clothing thermal resistances [clo] Yes
Recl.csv Local clothing evaporative resistances [m2Pa/w] Yes
Heat transfer rate qcnd.csv Local conductive heat fluxes [w/m2] Yes
qcnv.csv Local convective heat fluxes [w/m2] Yes
qEv.csv Local evaporative heat fluxes [w/m2] Yes
qLwR.csv Local long-wave radiant heat fluxes [w/m2] Yes
qSwR.csv Local short-wave radiant heat fluxes [w/m2] Yes
qsk.csv Local total heat fluxes [w/m2] Yes
Qsk_.csv Local total skin heat losses [w] Yes
Sweat and evaporation msw.csv Local sweat production rates [g/min] Yes
psk.csv Local vapor pressures at skin surface [pa] Yes
RHsk.csv Local relative humidity at skin surface [%] Yes
wsk.csv Local skin wettedness [%] Yes
accMsk.csv Local accumulated moisture at skin surface [g] Yes
Temperature Tcore.csv Core temperature of each body part [°C] Yes
Tsk.csv Local skin temperature (synmetrical) [°C] Yes
TskL&R.csv Local skin temperature (unsynmetrical) [°C] Yes
Tclo.csv Local cloth temperature at the surface (unsynmetrical) [°C] Yes
Physiological blood.csv Local blood circulation [ml/min] and artery/vein temperatures [°C] Yes
wblsk.csv Local skin blood perfusion rates [%Basal] Yes
Comfort and results CMF.csv Body thermal state variables and comfort -
CmfPrm.csv Environmental condition variables and comfort -
TRS.csv Thermal regulatory variables -
GlCalVar.csv Global Operative Temperatures and heat losses -
GlResults.csv Global environmental, physiological, regulatory, and comfort variables -
results.csv Globas physiological and regulatory results -
Disc.csv Local discomfort (LPPD) [%] Yes