Input Schemas

Input File Structure Schema

Input file files are organized as shown in the input file structure schema. Schemas for the objects referenced are shown below.

Schema properties shown in bold are required.

type	object
properties
version	Version of input file.
	type	string
fluid	Object used to define parameters related to the circulation fluid.
	type	object
grout	Object used to define parameters related to grout material.
	type	object
soil	Object used to define parameters related to soil material.
	type	object
pipe	Object used to define parameters related the pipes.
	type	object
borehole	Object used to define parameters related the borehole.
	type	object
simulation	Object used to define parameters related to simulation.
	type	object
geometric_constraints	Object used to define geometric constraint parameters for the selected design algorithm.
	type	object
design	Object used to define parameters related to design and sizing.
	type	object
loads	Object used to define loads for design and sizing.
	type	object

Borehole Input Schema

type	object
properties
buried_depth	Depth of top of borehole below the ground surface.
	type	number
	minimum	0
	units	m
diameter	Diameter of borehole.
	type	number
	units	m

Design Input Schema

type	object
properties
flow_rate	Volumetric design flow rate. Value specified will be either the system or per-borehole flow rate depending on the ‘flow_type’ set.
	type	number
	minimum	0
	units	l/s
flow_type	Indicates whether the design volumetric flow rate set on on a per-borehole or system basis.
	type	string
	enum	BOREHOLE, SYSTEM
max_eft	Maximum heat pump entering fluid temperature.
	type	number
	units	C
min_eft	Minimum heat pump entering fluid temperature.
	type	number
	units	C
max_boreholes	Maximum number of boreholes in search. Optional. Applies to rectangular and near-square design algorithms. If unspecified, the search space will be bounded by the size of the GHE boundary.
	type	number
continue_if_design_unmet	Causes to return the best available borehole field configuration rather than fail if design conditions are unmet. Optional. Default False.
	type	boolean

Fluid Input Schema

type	object
properties
fluid_name	Circulation fluid type.
	type	string
	enum	WATER, ETHYLALCOHOL, ETHYLENEGLYCOL, METHYLALCOHOL, PROPYLENEGLYCOL
concentration_percent	Mass fraction concentration percent of circulation fluid. e.g.: ‘0’ indicates pure water; ‘20’ indicates 20% antifreeze, 80% pure water.
	type	number
	maximum	60
	minimum	0
	units	percent
temperature	Average design fluid temperature at peak conditions.
	type	number
	units	C

Geometric Constraint Input Schemas

Input schemas for the geometric constraints are shown below. Each respective schema will describes how to each design method is applied.

Near-Square

type	object
properties
length	Horizontal side-length of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
b	Borehole-to-borehole spacing.
	type	number
	minimum	0
	units	m
max_height	Maximum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
min_height	Minimum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
method	Design algorithm specified.
	type	string
	const	NEARSQUARE

Rectangle

type	object
properties
length	Horizontal length of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
width	Horizontal width of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
b_min	Minimum borehole-to-borehole spacing.
	type	number
	minimum	0
	units	m
b_max	Maximum borehole-to-borehole spacing.
	type	number
	minimum	0
	units	m
max_height	Maximum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
min_height	Minimum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
method	Design algorithm specified.
	type	string
	const	RECTANGLE

Bi-Rectangle

type	object
properties
length	Horizontal length of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
width	Horizontal width of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
b_min	Minimum borehole-to-borehole spacing.
	type	number
	minimum	0
	units	m
b_max_x	Maximum borehole-to-borehole spacing in x-direction.
	type	number
	minimum	0
	units	m
b_max_y	Maximum borehole-to-borehole spacing in y-direction.
	type	number
	minimum	0
	units	m
max_height	Maximum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
min_height	Minimum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
method	Design algorithm specified.
	type	string
	const	BIRECTANGLE

Bi-Zoned Rectangle

type	object
properties
length	Horizontal length of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
width	Horizontal width of property boundary defining surface area available for ground heat exchanger.
	type	number
	minimum	0
	units	m
b_min	Minimum borehole-to-borehole spacing.
	type	number
	minimum	0
	units	m
b_max_x	Maximum borehole-to-borehole spacing in x-direction.
	type	number
	minimum	0
	units	m
b_max_y	Maximum borehole-to-borehole spacing in y-direction.
	type	number
	minimum	0
	units	m
max_height	Maximum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
min_height	Minimum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
method	Design algorithm specified.
	type	string
	const	BIZONEDRECTANGLE

Bi-Rectangle Constrained

type	object
properties
b_min	Minimum borehole-to-borehole spacing.
	type	number
	minimum	0
	units	m
b_max_x	Maximum borehole-to-borehole spacing in x-direction.
	type	number
	minimum	0
	units	m
b_max_y	Maximum borehole-to-borehole spacing in y-direction.
	type	number
	minimum	0
	units	m
max_height	Maximum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
min_height	Minimum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
property_boundary	(x, y) coordinate points of closed polygon defining property boundary. Points should be entered in a counter-clockwise fashion.
	type	array
	units	m
	items	type	array
		items	type	array
			items	type	number
				minimum	0
			maxItems	2
			minItems	2
no_go_boundaries	(x, y) coordinate points of closed polygon defining go/no-go boundaries. Go/no-go zones must lie within the area defined in ‘property_boundary’. Points should be entered in a counter-clockwise fashion.
	type	array
	units	m
	items	type	array
		items	type	array
			items	type	number
				minimum	0
			maxItems	2
			minItems	2
method	Design algorithm specified.
	type	string
	const	BIRECTANGLECONSTRAINED

Rowwise

type	object
properties
perimeter_spacing_ratio	The ratio between the minimum spacing between boreholes placed along the property and no-go zones and the standard borehole-to-borehole spacing used for internal boreholes.
	type	number
	minimum	0
	units	-
max_spacing	The largest minimum spacing that will be used to generate a RowWise field.
	type	number
	minimum	0
	units	m
min_spacing	The smallest minimum spacing that will be used to generate a RowWise field.
	type	number
	minimum	0
	units	m
spacing_step	The distance in spacing from the design found in the first part of first search to exhaustively check in the second part.
	type	number
	minimum	0
	units	m
max_rotation	The maximum rotation of the rows of each field relative to horizontal that will be used in the search.
	type	number
	maximum	90
	minimum	-90
	units	degrees
min_rotation	The minimum rotation of the rows of each field relative to horizontal that will be used in the search.
	type	number
	maximum	90
	minimum	-90
	units	degrees
rotate_step	Step size for field rotation search.
	type	number
	units	degrees
max_height	Maximum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
min_height	Minimum height, or active length, of each borehole heat exchanger.
	type	number
	minimum	0
	units	m
property_boundary	(x, y) coordinate points of closed polygon defining property boundary. Points should be entered in a counter-clockwise fashion.
	type	array
	units	m
	items	type	array
		items	type	number
			minimum	0
		maxItems	2
		minItems	2
no_go_boundaries	(x, y) coordinate points of closed polygon defining go/no-go boundaries. Go/no-go zones must lie within the area defined in ‘property_boundary’. Points should be entered in a counter-clockwise fashion.
	type	array
	units	m
	items	type	array
		items	type	array
			items	type	number
				minimum	0
			maxItems	2
			minItems	2
method	Design algorithm specified.
	type	string
	const	ROWWISE

Grout Input Schema

type	object
properties
conductivity	Thermal conductivity.
	type	number
	minimum	0
	units	W/m-K
rho_cp	Volumetric heat capacity.
	type	number
	minimum	0
	units	J/m^3-K

Loads Input Schema

type	object
properties
ground_loads	Annual, hourly heat extraction and heat rejection loads of the ground heat exchanger. Positive value indicate heat extraction, negative values indicate heat rejection.
	type	array
	units	W
	items	type	number
	maxItems	8760
	minItems	8760
heat_pump_loads	This field is currently unused.
	type	array
	units	W
	items	type	number
	maxItems	8760
	minItems	8760

Pipe Input Schemas

Input schemas for different pipe types are shown below.

Coaxial

type	object
properties
inner_pipe_d_in	Inner pipe inner diameter.
	type	number
	minimum	0
	units	m
inner_pipe_d_out	Inner pipe outer diameter.
	type	number
	minimum	0
	units	m
outer_pipe_d_in	Outer pipe inner diameter.
	type	number
	minimum	0
	units	m
outer_pipe_d_out	Outer pipe outer diameter.
	type	number
	minimum	0
	units	m
roughness	Surface roughness.
	type	number
	minimum	0
	units	m
conductivity_inner	Thermal conductivity of inner pipe.
	type	number
	minimum	0
	units	W/m-K
conductivity_outer	Thermal conductivity of outer pipe.
	type	number
	minimum	0
	units	W/m-K
rho_cp	Volumetric heat capacity.
	type	number
	minimum	0
	units	J/m^3-K
arrangement	Pipe arrangement specified.
	type	string
	const	COAXIAL

Single U-tube, Double U-tube

type	object
properties
inner_diameter	Inner diameter of pipe.
	type	number
	minimum	0
	units	m
outer_diameter	Outer diameter of pipe.
	type	number
	minimum	0
	units	m
shank_spacing	Spacing between up/down legs of u-tube pipe, as measured from nearest outer surfaces of each pipe (o<– s –>o).
	type	number
	minimum	0
	units	m
roughness	Surface roughness of pipe.
	type	number
	minimum	0
	units	m
conductivity	Thermal conductivity.
	type	number
	minimum	0
	units	W/m-K
rho_cp	Volumetric heat capacity.
	type	number
	minimum	0
	units	J/m^3-K
arrangement	Pipe arrangement specified.
	type	string
	enum	SINGLEUTUBE, DOUBLEUTUBESERIES, DOUBLEUTUBEPARALLEL

Simulation Input Schema

type	object
properties
start_month	This field is currently unused.
	type	string
	enum	JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
	default	JANUARY
num_months	Number of months used in ground heat exchanger sizing.
	type	number
	minimum	1
	units	months
timestep	This field is currently unused. Simulation timestep used in ground heat exchanger sizing. ‘HYBRID’ is the only option currently available.
	type	string
	enum	HYBRID, HOURLY
	default	HYBRID

Soil Input Schema

type	object
properties
conductivity	Thermal conductivity.
	type	number
	minimum	0
	units	W/m-K
rho_cp	Volumetric heat capacity.
	type	number
	minimum	0
	units	J/m^3-K
undisturbed_temp	Undisturbed, far-field soil temperature.
	type	number
	units	C