ajos3 2025.2

Adapted Jos-3 is a numerical model to simulate human thermal physiology.

adapted Joint system thermoregulation model (aJOS-3)

adapted Joint system thermoregulation model (JOS-3) is a numerical model to simulate human thermal physiology variables such as skin temperature, core temperature, heart rate, dehydration rate.

This model is an adaptation of the version 3.0.3.2 of JOS-3 model available on : https://github.com/TanabeLab/JOS-3 under MIT Licence Copyright (c) 2020 Yoshito Takahashi (Y. Takahashi, A. Nomoto, S. Yoda, R. Hisayama, M. Ogata, Y. Ozeki, S. Tanabe, Thermoregulation Model JOS-3 witheNew Open Source Code, Energy & Buildings (2020), doi: https://doi.org/10.1016/j.enbuild.2020.110575)

Please cite us if you use this package and describe which version you used: Sondaz, C., Merlier, L., Harpet, C., Kuznik, F., Design and validation of an individualizable thermophysiological model to assess thermal, hydric and cardiovascular strain. Sustainable Cities and Society 129 (2025), doi : https://doi.org/10.1016/j.scs.2025.106436

Requirement

• python3
• numpy

For storage of results and visualization

• pandas
• matplotlib

Model Description

aJOS-3 is an extension of the JOS-3 model.
It simulates thermophysiological responses of the human body, accounting for individual characteristics and transient, non-uniform environmental conditions.

The body is represented by 17 cylindrical or spherical segments. Each segment includes:

• Core node
• Skin node
• Artery node
• Vein node

In limb segments, an additional superficial vein node** is included.

The model covers a wide range of thermoregulatory responses:

• Vasodilation
• Vasoconstriction
• Sweating
• Shivering
• Non-shivering thermogenesis
• Arteriovenous anastomosis

---

New functionalities of aJOS-3

Compared to JOS-3, aJOS-3 introduces new functionalities:

• Dehydration rate calculation
  [ \text{Dehydration rate} = \frac{\text{Water loss – Water intake}}{\text{Body weight}*100} ]

• (Optional) Model of dehydration effects on sweating and vasodilation
  (based on Deng et al., 2020)

• Heart rate calculation
  (based on Kraning & Gonzalez, 1997)

Usage

Step 0: Import packages

from ajos3 import aJOS3
import numpy as np
import pandas as pd
import matplotlib as plt

Step 1: Build model

Parameters for aJOS3 class:

• height (float, optional) : Body height [m]. The default is 1.72.

• weight (float, optional) : Body weight [kg]. The default is 74.43.

• fat (float, optional) : Fat percentage [%]. The default is 15.

• age (int, optional) : Age [years]. The default is 20.

• sex (str, optional) : Sex ("male" or "female"). The default is "male".

• ci (float, optional) : Cardiac index [L/min/m2]. The default is 2.6432.

• bmr_equation (str, optional) : BMR equation. The default is "harris-benedict".

• bsa_equation (str, optional) : BSA equation. The default is "dubois".

  • You can choose "dubois", "fujimoto", "kruazumi", "takahira".

• ex_output (list/int, optional) : Extra output. The default is "None", which outputs only important parameters such as local skin temperatures or core temperature.

  • Set the parameters as the list format. (for example, if you want to see the data of ) ["BFsk", "BFcr", "Tar"].
  • If you want to see the all outputs, set ex_output to "all".

• Vo2_max_kg (float, optional) : Maximal aerobic capacity [ml/kg/min]. The default value is for a 20 years old man from Loe et al 2013 = 54.4 ml/kg/min : 10.1371/journal.pone.0064319

• Vo2_max_default (boolean, optional) : If True, Vo2 max is equal to default value according to age and sex. The default value is True.

Example

model = aJOS3(height = 1.8, 
              weight = 75,
              fat = 15, 
              age = 20, 
              sex = "male", 
              ci=2.59,
              Vo2_max_kg = 54.4, 
              Vo2_max_default = False,
              ex_output = None)
              
#(optional) change model options : e.g.activate effect of dehydration
model.options = {
        "nonshivering_thermogenesis": True,
        "cold_acclimated": False,
        "shivering_threshold": False,
        "limit_dshiv/dt": False,
        "bat_positive": False,
        "ava_zero": False,
        "shivering": False,
        "dehydration" : True} #True = effect of dehydration on sweating and vasodilation; False = no effect of dehydration

Step 2: Set Environmental and Behavioral Conditions

Environmental conditions and clothing insulation can be specified for the entire body or for each body part individually (using either a Python list or a numpy.ndarray). For each body part inputs, List input must have 17 elements, corresponding to the following body parts:
Head, Neck, Chest, Back, Pelvis, Left-Shoulder, Left-Arm, Left-Hand,
Right-Shoulder, Right-Arm, Right-Hand, Left-Thigh, Left-Leg, Left-Foot,
Right-Thigh, Right-Leg, Right-Foot.

To simulate transient conditions, alternate between entering environmental information and executing the simulate() method. After the simulate() method is executed, the environment input values are inherited, so you only need to enter the input parameters that you want to change.

Environmental and behavioral Parameters

• Ta (float or list) : Air temperature [oC].
• Tr (float or list) : Mean radiant temperature [oC].
• To (float or list) : Operative temperature [oC]. This parameter can be input instead of Ta and Tr
• Va (float or list) : Air velocity [m/s].
• RH (float or list) : Relative humidity [%].
• Icl (float or list) : Clothing insulation [clo].
• Icl_evap (float or list) : Clothing vapor permeation efficiency [-]
• PAR (float) Physical activity ratio [-]. The default is 1.2 (for sitting quietly).
• posture (str) : posture [-]. The default is "standing".
  • choose posture from "standing", "sitting" or "lying".
  • This parameter affects convective and radiant heat transfer coefficients for local body parts
• hydration (float) : Amount of water ingested (g/s). The default is 0g/s

Example

# Set the first condition
model.Ta = 28  # Air temperature [oC]
model.Tr = 30  # Mean radiant temperature [oC]
model.RH = 40  # Relative humidity [%]
model.PAR = 1.2  # Physical activity ratio [-], assuming a sitting position
model.Icl = 0.15 # Clothing insulation [clo]
model.posture = 'sitting' # Posture [-], assuming a sitting position
model.Va = np.array([ # Air velocity [m/s], assuming to use a desk fan
    0.2, # Head
    0.4, # Neck
    0.4, # Chest
    0.1, # Back
    0.1, # Pelvis
    0.4, # Left-Shoulder
    0.4, # Left-Arm
    0.4, # Left-Hand
    0.4, # Right-Shoulder
    0.4, # Right-Arm
    0.4, # Right-Hand
    0.1, # Left-Thigh
    0.1, # Left-Leg
    0.1, # Left-Foot
    0.1, # Right-Thigh
    0.1, # Right-Leg
    0.1, # Right-Foot
])
model.hydration = 200/24/60/60 #water intake - urine loss [g/s]

# Execute JOS-3 model
model.simulate(times=30, # Number of loops of a simulation
               dtime=60, # Time delta [sec]. The default is 60.
               )  # Exposure time = 30 [loops] * 60 [sec] = 30 [min]
               
# Set the next condition (You only need to change the parameters that you want to change)
model.To = 35
model.simulate(times=60,
               dtime=60, 
               ) 
               
# Set the next condition
model.PAR = 3.0
model.simulate(times=30,
               dtime=60, 
               ) 
               
# Set the next condition 
model.To = 25
model.PAR = 1.2
model.simulate(times=30,
               dtime=60, 
               ) 

Step 3: Output results

Default output parameters

• CycleTime: The counts of executing cycle calculation [-]
• ModTime : Simulation times [sec]
• dt : Time delta of the model [sec]
• TskMean : Mean skin temperature of the body [oC]
• Tsk : Skin temperature of the body part [oC]
• Tcr : Core temperature of the body part [oC]
• Delta_Tcr_Tsk : Core-to-skin temperature gradient [oC]
• WetMean : Mean skin wettedness of the body [-]
• Wet : Local skin wettedness of the body part [-]
• Wle : Weight loss rate by the evaporation and respiration of the whole body [g/sec]
• de : Dehydration rate [%]
• hydration : Amount of water ingested (g/s)
• CO : Cardiac output (the sum of the whole blood flow) [L/h]
• HR : Heart Rate [bpm]
• Met : Total heat production of the whole body [W]
• RES : Heat loss by respiration [W]
• THLsk : Heat loss from the skin of the body part [W]

Example code to show and save results

df_results = pd.DataFrame(model.dict_results())

#plot (e.g. Heart rate [bpm])
df_results.HR.plot()
plt.show()

#save as csv file 
model.to_csv('example_readme.csv')

Extra output parameters

• Age : Age [years]
• BFava_foot: AVA blood flow rate of one foot [L/h]
• BFava_hand: AVA blood flow rate of one hand [L/h]
• BFcr : Core blood flow rate of the body part [L/h]
• BFfat : Fat blood flow rate of the body part [L/h]
• BFms : Muscle blood flow rate of the body part [L/h]
• BFsk : Skin blood flow rate of the body part [L/h]
• BSA : Body surface area of the body part [m2]
• BSAtot : Total body surface area [m2]
• Emax : Maximum evaporative heat loss at the skin of thebody part [W]
• Esk : Evaporative heat loss at the skin of the body part [W]
• Esweat : Evaporative heat loss at the skin by only sweating of the body part [W]
• EsweatTot: Total evaporative heat loss at the skin by only sweating [W]
• Fat : Body fat rate [%]
• Height : Body heigh [m]
• Icl : Clothing insulation value of the body part [clo]
• Icl_evap: Clothing vapor permeation efficiency of the body part [-]
• LHLsk : Latent heat loss at the skin of the body part [W]
• Mbasecr : Core heat production by basal metabolism of thebody part [W]
• Mbasefat: Fat heat production by basal metabolism of thebody part [W]
• Mbasems : Muscle heat production by basal metabolism of thebody part [W]
• Mbasesk : Skin heat production by basal metabolism of thebody part [W]
• Mnst : Core heat production by non-shivering of the body part [W]
• Mshiv : Core or muscle heat production by shivering of thebody part [W]
• Mwork : Core or muscle heat production by work of the body part [W]
• Name : Name of the model [-]
• PAR : Physical activity ratio [-]
• Qcr : Core total heat production of the body part [W]
• Qfat : Fat total heat production of the body part [W]
• Qms : Muscle total heat production of the body part [W]
• Qsk : Skin total heat production of the body part [W]
• RESlh : Latent heat loss by respiration [W]
• RESsh : Sensible heat loss by respiration [W]
• RH : Relative humidity of the body part [%]
• Ret : Total evaporative heat resistance of the body part [m2.kPa/W]
• Rt : Total heat resistance of the body part [m2.K/W]
• SHLsk : Sensible heat loss at the skin of the body part [W]
• Setptcr : Set point skin temperature of the body part [oC]
• Setptsk : Set point core temperature of the body part [oC]
• Sex : Male or female [-]
• Ta : Air temperature of the body part [oC]
• Tar : Arterial temperature of the body part [oC]
• Tcb : Central blood temperature [oC]
• Tfat : Fat temperature of the body part [oC]
• Tms : Muscle temperature as the body part [oC]
• To : Operative temperature of the body part [oC]
• Tr : Mean radiant temperature of the body part [oC]
• Tsve : Superfical vein temperature of the body part [oC]
• Tve : Vein temperature of the body part [oC]
• Va : Air velocity of the body part [m/s]
• Vo2max : Maximal aerobic capacity [ml/min]
• Vo2max_kg: Maximal aerobic capacity per kg [ml/kg/min]
• Weight : Body weight [kg]

Check the output parameters documentation

print(model.show_outparam_docs())

Author

• Célia Sondaz ([e-mail])
• Lucie Merlier
• Frédéric Kuznik

Licence

aJOS 3 is under CECILL FREE SOFTWARE LICENSE. Based on code JOS-3 originally created by Yoshito Takahashi (2020) under MIT License