Foundation¶
The description of the foundation design is provided within the two-dimensional context. This profile is applied along the entire perimeter of the foundation.
The foundation insulation and structural components are defined by (up to) six sub-objects. These objects allow the user to flexibly describe any foundation construction.
Example:
Foundation:
Foundation Depth: 0.0 # [m]
Polygon:
- [0, 0] # [m, m]
- [0, 20] # [m, m]
- [20, 20] # [m, m]
- [20, 0] # [m, m]
Soil: Typical Soil # Material reference
Slab:
Layers:
-
Material: Concrete # Material reference
Thickness: 0.2032 # [m]
Wall:
Layers:
-
Material: Concrete # Material reference
Thickness: 0.3048 # [m]
Height Above Grade: 0.3048 # [m]
Height: 0.508 # [m]
Interior Horizontal Insulation:
Depth: 0.2032 # [m]
Width: 0.4064 # [m]
Material: XPS # Material reference
Thickness: 0.0508
Interior Vertical Insulation:
Depth: 0.2032 # [m]
Material: XPS # Material reference
Thickness: 0.0508 # [m]
Indoor Air Temperature: 295.372 # [K]
Foundation Depth¶
Foundation Depth
defines the distance from the wall top to the floor. This value is used to characterize the type of foundation (slab, crawlspace, or basement). For example, a value of zero would represent a sla and a value near 2 meters would represent a basement.
Required: | Yes |
Type: | Numeric |
Units: | m |
Polygon¶
The foundation shape is defined by the description of a single polygon. The perimeter of this polygon defines the location of the interior surface of the foundation wall. The positioning of the foundation insulation and structural components are translated into three-dimensional space internally.
The polygon is specified by a list of x-y Cartesian vertices tracing the foundation perimeter in a clockwise fashion. When simulating in three-dimensions, the polygon must be rectilinear (comprised only of right angles).
Example:
Polygon:
- [0, 20]
- [15, 20]
- [15, 30]
- [30, 30]
- [30, 17]
- [22, 17]
- [22, 0]
- [12, 0]
- [12, 10]
- [0, 10]
Required: | Yes |
Type: | List [N] of lists [2] of numerics |
Units: | m |
Soil¶
Represents the soil surrounding the building foundation.
Required: | Yes |
Type: | Material reference |
Slab¶
This defines the costruction of the floor slab in the foundation. This is not required. If there is no slab defined for a given foundation, then the floor is exposed soil.
Example:
Slab:
Layers:
-
Material: XPS # Material reference
Thickness: 0.0508 # [m]
-
Material: Concrete # Material reference
Thickness: 0.2032 # [m]
Required: | No |
Type: | Compound object |
Layers¶
Layers are specified as a list of material references, and thickness values from the outtermost layer to the innermost layer (at the floor surface). A layer of insulation can be added to model whole-slab insulation.
Required: | Yes |
Type: | List of layers (a material and a thickness) |
Emissivity¶
Interior emissivity of the slab used for interior long-wave radiation calculations.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.8 |
Wall¶
This defines the costruction of the foundation wall. This is not required. If there is no wall defined for a given foundation, then the wall is exposed soil.
Example:
Wall:
Height: 2.95 # [m]
Height Above Grade: 0.3048 # [m]
Layers:
-
Material: XPS # Material reference
Thickness: 0.0508 # [m]
-
Material: Concrete # Material reference
Thickness: 0.2032 # [m]
-
Material: XPS # Material reference
Thickness: 0.0508 # [m]
Required: | No |
Type: | Compound object |
Height¶
The height of the wall describes the distance from the wall top to the bottom of the foundation footer (the footer is not modeled separately). This value should generally be greater than that of the Foundation Depth combined with the total thickness of the slab.
Required: | Yes |
Type: | Numeric |
Units: | m |
Height Above Grade¶
The height of the wall top relative to the grade (z = 0).
Required: | Yes |
Type: | Numeric |
Units: | m |
Layers¶
Layers are specified as a list of material references, and thickness values from the outtermost layer to the innermost layer (at the interior wall surface).
Interior Emissivity¶
Interior emissivity of the wall used for interior long-wave radiation calculations.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.8 |
Exterior Emissivity¶
Exterior emissivity of the wall used for exterior long-wave radiation calculations.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.8 |
Exterior Absorptivity¶
Exterior absorptivity of the wall used for calculating absorbed solar radiation.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.8 |
Interior Horizontal Insulation¶
This defines the position, dimensions, and material of interior horizontal insulation. Interior horizontal insulation begins at the wall’s interior surface and extends inward and downward to a user-specified width and thickness at a user-specified depth at or below the Foundation Depth.
Example:
Interior Horizontal Insulation:
Material: XPS # Material reference
Thickness: 0.0508 # [m]
Depth: 0.2032 # [m]
Width: 0.4064 # [m]
Required: | No |
Type: | Compound object |
Depth¶
Depth of the insulation measured from the wall top to the top of the insulation.
Required: | Yes |
Type: | Numeric |
Units: | m |
Width¶
Width of the insulation extending from the interior wall surface.
Required: | Yes |
Type: | Numeric |
Units: | m |
Interior Vertical Insulation¶
This defines the position, dimensions, and material of interior vertical insulation. Interior vertical insulation begins at the wall top and extends downward and inward to a user-specified depth and thickness. The depth can be specified to model partial interior wall insulation.
Example:
Interior Vertical Insulation:
Material: XPS # Material reference
Thickness: 0.0508 # [m]
Depth: 0.6096 # [m]
Required: | No |
Type: | Compound object |
Depth¶
Depth of the insulation measured from the wall top to the bottom of the insulation.
Required: | Yes |
Type: | Numeric |
Units: | m |
Exterior Horizontal Insulation¶
This defines the position, dimensions, and material of exterior horizontal insulation. Exterior horizontal insulation begins at the wall’s exterior surface and extends outward and downward to a user-specified width and thickness at a user-specified depth at or below the grade level.
Example:
Exterior Horizontal Insulation:
Material: XPS # Material reference
Thickness: 0.0508 # [m]
Depth: 0.3048 # [m]
Width: 0.6096 # [m]
Required: | No |
Type: | Compound object |
Depth¶
Depth of the insulation measured from the wall top to the top of the insulation.
Required: | Yes |
Type: | Numeric |
Units: | m |
Width¶
Width of the insulation extending from the interior wall surface.
Required: | Yes |
Type: | Numeric |
Units: | m |
Exterior Vertical Insulation¶
This defines the position, dimensions, and material of exterior vertical insulation. Exterior vertical insulation begins at the wall top and extends downward and outward to a user-specified depth and thickness.
Example:
Exterior Vertical Insulation:
Material: XPS # Material reference
Thickness: 0.0508 # [m]
Depth: 2.0 # [m]
Required: | No |
Type: | Compound object |
Depth¶
Depth of the insulation measured from the wall top to the bottom of the insulation.
Required: | Yes |
Type: | Numeric |
Units: | m |
Indoor Air Temperature Method¶
Allows the user to choose between having a constant indoor temperature for the duration of the simulaiton or to reference temperatures from a file.
Required: | No |
Type: | Enumeration |
Values: | FILE or CONSTANT |
Default: | CONSTANT |
Indoor Air Temperature File¶
If Indoor Air Temperature Method is FILE
the indoor dry-bulb temperature (in Kelvin) will be set using hourly values defined in a comma separted value (CSV) file.
Example:
Indoor Air Temperature File:
Name: ../path/to/file.csv
Index: [1,1]
Required: | No |
Type: | Compound object |
Index¶
A list of two values corresponding to the row and column where the hourly data begins in the file. A value of [0, 0]
starts at the first row and first column. A value of [0,1]
starts at the first row and second column.
Required: | Yes |
Type: | List [2] of integers |
Indoor Air Temperature¶
If Indoor Air Temperature Method is CONSTANT
the indoor dry-bulb temperature will be set using this value. If Indoor Air Temperature Method is FILE
, then this is not required.
Required: | Depends |
Type: | Numeric |
Units: | K |
Outdoor Air Temperature Method¶
Allows the user to choose between having a constant outdoor temperature for the duration of the simulaiton or to reference temperatures from the weather file.
Required: | No |
Type: | Enumeration |
Values: | WEATHER-FILE or CONSTANT |
Default: | WEATHER-FILE |
Outdoor Air Temperature¶
If Outdoor Air Temperature Method is CONSTANT
the outdoor dry-bulb temperature will be set using this value. If Outdoor Air Temperature Method is WEATHER-FILE
, then this is not required.
Required: | Depends |
Type: | Numeric |
Units: | K |
Soil Absorptivity¶
Solar absorptivity of the soil or grade surface.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.8 |
Soil Emissivity¶
Long-wave emissivity of the soil or grade surface.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.8 |
Surface Roughness¶
Represents the relief of the surface. This value is used to calculate forced convection and the wind speed near the grade surface. Roughness values in the table below are converted from the more qualitative rougness values used in DOE-2 and EnergyPlus. Estimates for soil, gravel, and grass are also shown.
Example Surface | Roughness [m] |
---|---|
Glass | 0.0000 |
Smooth Plaster | 0.0044 |
Clear Pine | 0.0052 |
Concrete | 0.0208 |
Brick | 0.0268 |
Stucco | 0.0468 |
Soil | 0.0500 |
Gravel | 0.1200 |
Grass | 0.3000 |
Required: | No |
Type: | Numeric |
Units: | m |
Default: | 0.3 |
Local Boundary Layer Thickness¶
Local boundary layer thickness used for calculating local wind speeds from weather file wind speeds.
Required: | No |
Type: | Numeric |
Units: | m |
Default: | 370 |
Local Terrain Exponent¶
Local terrain exponent used for calculating local wind speeds from weather file wind speeds.
Required: | No |
Type: | Numeric |
Units: | dimensionless |
Default: | 0.22 |
Orientation¶
Defines the orientation of the building clockwise relative to North (East = \(\pi/2\), South = \(\pi\), West = \(3\pi/2\)). This is used to calculate the solar incidence and wind direction relative to exterior vertical foundation surfaces.
Required: | No |
Type: | Numeric |
Units: | radians |
Default: | 0.0 |
Perimeter Surface Width¶
This value is used to define a portion of the slab’s perimeter separately from the slab core. This will affect the meshing of the slab, but is intended primarily for separate output reporting for each region.
Required: | No |
Type: | Numeric |
Units: | m |
Default: | 0.0 |
Output Report¶
The output report defines what variables are written to the CSV output file and how often they are written.
Example:
Output Report:
Minimum Reporting Frequency: 60 # [min]
Reports:
- 0 # Slab Core Average Heat Flux [W/m2]
- 1 # Slab Core Average Temperature [K]
- 2 # Slab Core Average Effective Temperature [C]
- 3 # Slab Core Total Heat Transfer Rate [W]
- 4 # Slab Perimeter Average Heat Flux [W/m2]
- 5 # Slab Perimeter Average Temperature [K]
- 6 # Slab Perimeter Average Effective Temperature [C]
- 7 # Slab Perimeter Total Heat Transfer Rate [W]
- 8 # Slab Average Heat Flux [W/m2]
- 9 # Slab Average Temperature [K]
- 10 # Slab Total Heat Transfer Rate [W]
- 11 # Wall Average Heat Flux [W/m2]
- 12 # Wall Average Temperature [K]
- 13 # Wall Average Effective Temperature [C]
- 14 # Wall Total Heat Transfer Rate [W]
- 15 # Foundation Average Heat Flux [W/m2]
- 16 # Foundation Average Temperature [K]
- 17 # Foundation Total Heat Transfer Rate [W]
Required: | No |
Type: | Compound object |
Minimum Reporting Frequency¶
Kiva can provide timeseries output at the same interval as the timestep. This input will override to delay output and write it a a lower frequency. This helps to reduce the output size when running at very small timesteps.
Required: | No |
Type: | Integer |
Units: | min |
Default: | 60 |
Reports¶
This is a list of report ID numbers that Kiva will write to the CSV output file. The IDs and there corresponding output are listed in the table below:
When Perimeter Surface Width is not specified, the entire slab is considered to be “Core”.
“Effective Temperature” is used for preprocessed ground temperatures in whole-building simulation engines. These values represent the effective temperature on the ground’s side of the slab core, slab perimeter, or wall layers. When used in a whole-building simulation, the construction in the whole-building model should be the same as the layers defined for the respective surface in Kiva (ignoring any insulation objects).
Required: | No |
Type: | List [N] of integers |
Default: | No reports |
Output Snapshots¶
Output snapshots are used to graphically visualize domain temperatures and/or heat fluxes. Each series of snapshots is part of a list within the Output Snapshots object. A series consists of potentially many snapshots taken of a slice of the domain at a user-specified frequency between a start and end date.
Example:
Output Snapshots:
-
Directory: Output/Profile
Size: 800
Frequency: 1
Start Date: 2015-Dec-21
End Date: 2015-Dec-21
X Range: [0, 30]
Z Range: [-30, 0.3048]
Required: | No |
Type: | List [N] of compound objects |
Directory¶
Directory where snapshots are created. An ordered file name, XXXX.png
, identifies each snapshot within a series. For example, the 134th snapshot in a series with a directory name of Profile
will be created as Profile/0134.png
.
Required: | Yes |
Type: | Directory Path |
Size¶
The size in pixels of each snapshot file. Outputs are all generated as square images.
Required: | No |
Type: | Integer |
Units: | pixels |
Default: | 800 |
Frequency¶
The frequency, in hours, at which new snapshots are taken. The default is 36 hours so that the snapshots capture both nighttime and daytime output.
Required: | No |
Type: | Integer |
Units: | hours |
Default: | 36 |
Start Date¶
Specifies the start date of the snapshots. Snapshots begin at 12:00am of this day. This is specified as a date string (e.g., YYYY-Mon-DD, YYYY/MM/DD).
Required: | No |
Type: | Date string |
Default: | Simulation start date |
End Date¶
Specifies the end date of the snapshots. Snapshots end before 12:00am of the following day. This is specified as a date string (e.g., YYYY-Mon-DD, YYYY/MM/DD).
Required: | No |
Type: | Date string |
Default: | Simulation end date |
X Range¶
Defines the range the domain captured in the snapshot in the “X”-direction ([Xmin, Xmax]
). By default the X Range will show the entire extents of the “X” direction, and may not show the detail where heat is flowing near the foundaiton. For three-dimensional solutions, a slice along a plane in the “X”-direction can be specified by giving both Xmin
and Xmax
the same value.
The snapshot will round the range to the next cell division.
Required: | No |
Type: | List [2] of numerics |
Units: | m |
Default: | “X” extents of the domain |
Y Range¶
Defines the range the domain captured in the snapshot in the “Y”-direction ([Ymin, Ymax]
). By default the Y Range will show the entire extents of the “Y” direction, and may not show the detail where heat is flowing near the foundaiton. For three-dimensional solutions, a slice along a plane in the “Y”-direction can be specified by giving both Ymin
and Ymax
the same value. For two-dimensional simulations this should not be included.
The snapshot will round the range to the next cell division.
Required: | No |
Type: | List [2] of numerics |
Units: | m |
Default: | “Y” extents of the domain |
Z Range¶
Defines the range the domain captured in the snapshot in the “Z”-direction ([Zmin, Zmax]
). By default the Z Range will show the entire extents of the “Z” direction, and may not show the detail where heat is flowing near the foundaiton. For three-dimensional solutions, a slice along a plane in the “Z”-direction can be specified by giving both Zmin
and Zmax
the same value.
The snapshot will round the range to the next cell division.
Required: | No |
Type: | List [2] of numerics |
Units: | m |
Default: | “Z” extents of the domain |
Plot Type¶
Defines the type of output plotted. Options are TEMPERATURE
and HEAT-FLUX
. For HEAT-FLUX
, the user may also specify a Flux Direction for output.
Required: | No |
Type: | Enumeration |
Values: | TEMPERATURE or HEAT-FLUX |
Default: | TEMPERATURE |
Flux Direction¶
When Plot Type is HEAT-FLUX
, the snapshots show the magnitude of heat flux throughout the domain. This input allows the user to specify whether they want to display the overall magnitude, MAG
, or the magnitude in a given direciton, X
, Y
, or Z
.
Required: | No |
Type: | Enumeration |
Values: | MAG , X , Y , or Z |
Default: | MAG |
Unit System¶
Defines the units used in the output snapshots. Options are IP
(Inch-Pound), and SI
(International System). Keep in mind that regardless of this value, all other inputs are still defined in the SI unit system.
Required: | No |
Type: | Enumeration |
Values: | IP or SI |
Default: | SI |
Output Range¶
Specifies the range of output shown in the snapshots. The units of the range depend on the value of Plot Type and Unit System.
Required: | No |
Type: | List [2] of numerics |
Units: | Depends |
Default: | “Z” extents of the domain |
Color Scheme¶
Specifies the color scheme used within the Output Range. Options are:
CMR
, best color scheme where colors progress in brightness with magnitude (prints in black-and-white),JET
, like a rainbow(!), but doesn’t print well,NONE
, do not show any output. This can be used to illustrate meshing independent of results.
Required: | No |
Type: | Enumeration |
Values: | CMR , JET , or NONE |
Default: | CMR |
Mesh¶
Enables the display of the mesh (discretized cells).
Required: | No |
Type: | Boolean |
Default: | False |
Axes¶
Enables the display of the spatial axes, and the colorbar.
Required: | No |
Type: | Boolean |
Default: | True |
Number of Contours¶
Specifies the number of countours to generate between the values specified in Output Range.
Required: | No |
Type: | Integer |
Default: | 13 |