meta data for this page

API for the JHDTS Human Model


Features

  • Based on the original IESD-Fiala model
  • …

API Overview

Root Url: http://jhdts.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 http://jhdts.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
  • Headers: api_key={…}, session_key={…}
  • Body: none
curl -H "api_key: ..." -H "session_key: ..." http://jhdts.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
  • Headers: api_key={…}, session_key={…}
  • Body: {experiment data}
curl -H "api_key: ..." -H "session_key: ..." -H "Content-Type: application/json" -X POST -d '{experiment data}' http://jhdts.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}
  • Headers: api_key={…}, session_key={…}
  • Body: none
curl -H "api_key: ..." -H "session_key: ..." http://jhdts.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}
  • Headers: api_key={…}, session_key={…}
  • Body: none
curl -H "api_key: ..." -H "session_key: ..." http://jhdts.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}
  • Headers: api_key={…}, session_key={…}
  • Body: none
curl -H "api_key: ..." -H "session_key: ..." http://jhdts.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}
  • Headers: api_key={…}, session_key={…}
  • Body: none
curl -H "api_key: ..." -H "session_key: ..." http://jhdts.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 -H "api_key: ..." -H "session_key: ..." -X POST http://jhdts.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