HydroCAD Prefab Chamber file specification
   --------------------------------------------------
   Copyright (c) 2019 HydroCAD Software Solutions LLC
              -------------------------

Starting with version 7.0, HydroCAD provides direct support for a wide
range of prefabricated storage chambers.  Data for each chamber is
defined by a separate chamber definition file.  A set of pre-defined
chamber definitions are automatically installed in the HydroCAD
"Chambers" folder, and may be selected from within any HydroCAD project.

Additional definitions may be placed in this folder at any time, or
in the same folder as the project file(s) that employ them.

For the latest chamber definitions see www.hydrocad.net/chambers

Note: Circular and rectangular chambers can be modeling with one of the
      standard storage definitions and do NOT require a custom chamber.
      However, a chamber definition allows automatic layout of
      underground storage systems using the HydroCAD Chamber Wizard.

To view any chamber definition, double-click the file. If asked what
program you want to use to open the file, select "notepad".

HydroCAD 8.0 (and later) also includes a chamber report window which
makes it easy to view, compare, and create chamber definitions.  To
open the report select View | Chamber from the main menu, or click
the "View Chamber" button when editing the pond storage.

****** Guidelines for creating a new chamber definition file ******

The remainder of this document provides general guidelines for 
creating a custom chamber definition.  For additional assistance,
see one of the "Sample" chamber files that are installed with HydroCAD.
These files can also be used as templates when creating your chamber
definitions.

Each chamber file should be named using the manufacturer's name and
model designation, such as "Sample 100A", and must have an ".hcc" file
extension.  All files are in plain ASCII format as shown below.
Comments {shown in braces} do not appear in the actual files.

  Name=Sample 100A     {should match the file name}

  Comment=Sample chamber definition  {additional info as required}

  FileUnits=English   {English or Metric units allowed}

  Length=10        {individual chamber length}

  Width= 0.0  3.0  {bottom depth and corresponding width}
  Width= 1.2  2.4 
  Width= 1.8  2.0  {depth and width at successive increments...}
  Width= 2.4  1.2
  Width= 3.0  0.6 
  Width= 3.6  0.0  {overall depth and width at top of chamber}

The file must contain at least two stage definitions as required to
adequately describe the shape of the chamber.  Each stage includes
a depth value and the effective width at that depth.  The first
stage must have a depth of zero, and defines the width at the
bottom of the chamber.  The final stage must be at the top of the
chamber, and may have a zero or non-zero width as required.

Individual values must be separated by at least one space, and may
include decimal points and leading zeros as required.  Values may
be in feet or meters, depending on the selection of English or
metric units.  A single division or multiplication operation may be
used for convenience in expressing values.  For example, 4 inches
may be expressed as 4/12 instead of 0.33333333333

Note that each stage uses the "effective" width, such that the final
volume calculations correspond to the actual chamber volume at each
depth.  For thin-walled corrugated chambers, this value will fall
somewhere between the inside and outside width of the chamber.

As each chamber is selected in HydroCAD, its effective cross-sectional
area or volume is immediately calculated and display.  This value
should closely match the manufacturer's specification for the given
chamber.

Instead of defining chamber widths, incremental cross sections may be
specified, as shown below:

  IncSect= 1.2  .250  {cross-section from bottom to 1.2'}
  IncSect= 1.8  .200  {cross-section from 1.2' to 1.8'}
  IncSect= 2.4  .145  {cross-section from 1.8' to 2.4'}
  IncSect= 3.0  .045  {cross-section from 2.4' to top of chamber 3.0'}

If the actual storage is different than the amount described by the width
or cross-section data, it can be adjusted by using a storage multiplier:

  StoreMult=0.95      {reduce storage by 5% at all stages}

Values less than one will decrease the storage, while values greater
than one will increase the storage.

Starting with HydroCAD 10.0 build 25, incremental volumes may also be
specified, as shown below:

  IncVol= 1.2  .12  {volume from bottom to 1.2'}
  IncVol= 1.8  .10  {volume from 1.2' to 1.8'}
  IncVol= 2.4  .25  {volume from 1.8' to 2.4'}
  IncVol= 3.0  .50  {volume from 2.4' to top of chamber 3.0'}

********************** Thick-walled Chambers *********************

With HydroCAD 8.5 and later, a third column of data may be added to the
Width (or IncSect) lines in order to define the outside width (or cross-
section) of the chamber at each depth.  This allows for proper calculation
of the displacement for chambers with a significant wall thickness, such
as concrete galleys.  The Length statement may also include a second
parameter in order to define different inside and outside lengths.

Thick-walled chambers will usually have holes or openings in the wall,
which may have a significant effect on the internal and/or displaced
volume of the chamber.  Although the width or cross-section data can be
adjusted to allow for this volume, the StoreMult statement can be used
with two parameters to adjust the inside and displaced volume.  This
statement will increase the internal storage by 5% and decrease the
displaced volume by 2% :

  StoreMult= 1.05  0.98

For details see the "Sample 101A" chamber installed with HydroCAD.

HydroCAD 10.0 build 8 can allow for a perimeter wall that is often
integrated into the special concrete chambers used around the perimeter
of a chamber system. The PerimWall statement can be used to specify the
reduction in the internal storage volume for each section of perimeter wall.

  PerimWall=0.05  0.06

In this example, the internal volume will be reduced by 5% for each segment
of side wall and 6% for each segment of end wall.  This adjustment is made
after the StoreMult parameter has been applied.  If only one value is
specified, it is used for both the side walls and end walls.

HydroCAD 10.0 build 10 can add a border of a specific width around the
specified chamber layout.  This adjustment is made after the StoreMult
parameter has been applied.

  Border=2.0 3.0

In this example a 2' wide border is added to each side of the layout and a
3' wide border is added to each end.  If only one value is provided, it is
used as the border with for the sides and ends. The border storage will be
proportional to the central chamber definition, based on the relative surface
area.  If the border provides a different amount of storage per unit area, the
border storage can be adjust by a specified multiplier:

  BorderMult=0.97

This example will reduce the border storage to 97% of the core chamber storage
(per unit surface area).  The border outside volume is adjusted only if a
second parameter is specified:

  BorderMult=0.97  0.90

The ability to adjust the border outside volume was added in version 10.00 build 21.

********************* Constant depth increment ******************

In the preceding examples, storage was entered at uneven user-defined
depths.  You can also enter Width, IncSect, or IncVol data at even depth
increments by specifying a depth increment before the storage values:

  DepthInc= 1/12   {set one inch depth increment}

  IncSect= 0.201 0.199 0.181 0.164 0.160 {section data for 1,2,3,4,5"}
    -or-
  IncVol= 0.5 0.6 0.7 0.9 1.2  {incremental volume for 1,2,3,4,5"}
    -or-
  Width= 2.0  1.5  0.8  0.5  0.0  {widths at 0,1,2,3,4" depths}


When the DepthInc is specified, data values may be provided in one or
more lines, with any number of items per line.  This format does not
allow the outside storage or width to be specified, so it should be
used only with thin-walled chambers.

Starting with HydroCAD-10 build 25, repeated storage values can be specified
by using the letter 'x' followed by the repetition count:

  IncSect= 0.201 x5  0.199  0.150  {first value is repeated 5 times}

*********************** Wetted Area ******************************

If the chambers are arranged in multiple rows, the wetted area includes
the bottom area plus the submerged portion of the outermost sidewalls.
(The interior facing walls are excluded)  If the chambers are arranged
in a single row (or the row count is not specified) the wetted area includes
the bottom area plus the submerged portion of all sides.  In either case,
horizontal side-segments, such as a flat top, are excluded.

If the chamber allows for exfiltration through one or both ends, include
the following statement in the file:

  WettedEnds=2    {specify 0,1,2 ends, default is 0}

When using multiple chambers (as defined by the Storage Multiplier within
each project), this setting causes the end-area to be included for EACH of
the chambers.  But if the chambers are arranged end-to-end, such that only
one or two ends or each row are available for exfiltration, the number of
ends should be specified with a minus sign:

  WettedEnds=-2   {use -1 or -2, as required}

Note:  For most applications this setting will have no effect, since
exfiltration is generally calculated based on the area of the outer
material (e.g. stone backfill) in which the chamber is embedded.

********************* Multi-span Chambers ***************************

Although most chambers will consist of a single span, some products may
have several identical spans within a single unit.  In order to display
the correct number of spans in graphical reports, specify the number of
spans as follows:

  Spans=2  {indicates a chamber with 2 spans}

Note: This feature was added in HydroCAD-9 build 9 and does not effect
      calculation results.  The only effect of this statement is to
      accurately depict the multiple spans in graphical reports.

****************** Overall Chamber Dimensions ***********************

Unless otherwise specified, the overall chamber dimensions are assumed
to be the same as the outside width, height, and length, as defined above.
If the chamber has flanges or other protrusions that increase the overall
size, the actual dimensions can be specified as follows:

  Overall= 2.0  1.0  5.0   {width, height, length}

Although these values do not effect the actual storage calculations, they
are used for reporting and automatic chamber layout with HydroCAD-9 and
later.

*********** Chamber Overlap and the Row Length Adjustment ************

When the overall chamber length is greater than the effective length, this
indicates an overlap between adjacent chambers in each row, as commonly
occurs with plastic arch chambers.  When calculating the storage for each
chamber, HydroCAD uses the (shorter) effective length, so that the volume
of the overlap is not double-counted.  However, to get the exact volume for
each row, it is necessary to add the overlap length to each row, since the
starting (or ending) chamber contributes storage over its full length.
This "row length adjustment" occurs automatically with HydroCAD-10, which
adds the overlap to the effective length of each row.

With HydroCAD-10 (and later), the row length adjustment can also be
specified explicitly within the chamber definition as follows:

  RowAdjust=-3.5

Positive values will increase the length of each row, while negative values
will reduce the length.  Including a RowAdjust value will override the
automatic row length adjustment described above.

If there is no chamber overlap or RowAdjust parameter, the row length
adjustment can be set manually on the prefab storage chamber screen.  This
is useful for specific storage products, such a pipes, that can be cut to
custom lengths.  When using pipe storage, the recommended procedure is to
specify the total number of pipe sections in each row, and then set a
negative row length adjustment to indicate the amount being cut from the
final pipe in each row.

The row length adjustment can be displayed at one end of each row, or
split between the two ends of each row, depending on this parameter:

  SplitRowAdjsut=True  -or-  SplitRowAdjust=False

If SplitRowAdjust in not specified, it defaults to True when RowAdjust
is negative, or False if RowAdjust is zero or positive.

******************** Headers and  End Cap Storage  ***********************

HydroCAD-10 adds several new parameters for handling the storage volume
and layout of proprietary end caps and headers.  For an end-cap, the cap
volume and length can be specified with:

  CapVolume=1.2   {volume of each end-cap, in cubic feet or cubic-meters}
  CapLength=1.5   {length of each end-cap, in feet or meters}

When the CapVolume is specified, HydroCAD adds that amount of storage
to both ends of each row.  For a thick-walled chamber, the outside volume
may be specified as a second parameter on the line.

When CapLength is specified, the chamber wizard allows this additional
space at the both ends of each row when determining the overall size of
the stone field.

HydroCAD-10 allows for automatic layout and modeling of headers for certain
chambers.  This option is automatically enabled for pipe products, and disabled
for open-bottom chambers.  This default can be changed by including one of
the following statements:

  Headers=True   {enable headers}
  Headers=False  {disable headers}

Whenever headers are enabled, the actual number of headers (0, 1, or 2) may be
set within each storage definition in the HydroCAD project file.

************************ Nested and Offset Rows ************************

HydroCAD-10 adds two new parameters for handing nested and offset rows:

  Nesting=0.25   {Amount of nesting between adjacent rows}
  RowOffset=1.5  {Amount of offset for adjacent rows}

These parameters are used for products such as the LRM HydroDome, which
has curved sides that allow adjacent rows to be nested together, such that 
the installed width of adjacent rows is less than the sum off the overall
widths.  The row offset causes alternate rows to start at a different
positions, so the wide and narrow sections of adjacent chambers are properly
aligned.

************************* Stacked Chambers ***************************

Starting with HydroCAD-10 build 20, stacked chambers can be modeled by
specifying the number of stacked modules.  This avoids the need for
separate chamber definitions for each stack configuration.  Chamber
definitions that allow stacking must specify the maximum stack size:

  MaxSize=7   {maximum number of chambers that can be stacked}

The actual stack size is set by the user, and may be any integer from 1
up to the specified maximum.  This value is used as a vertical scale
factor to "stretch" the chamber by the specified amount. (1,2,3, etc.)

If the allowable stack sizes are not consecutive integers, a list of
permitted sizes can be specified directly:

  Sizes=1.0  1.5  2.0  2.5  3.0

The user may only select from the specified values, which is then used as
a vertical scale factor.

Instead of using a fractional stack size, the actual chamber heights may
be specified:

  Heights= 110  210  310  410  {100mm increments plus 10mm base}

These heights would be referenced by consecutive sizes from 1-4, or used
together with a custom list of sizes:

  Sizes=small medium large xlarge  {sizes are alphanumeric}
  Heights=110  210    310   410

***********************  Multi-Size Chambers  *****************************

Multi-size chambers are traditionally supported by providing a different
chamber definition file for each available size.  Starting with HydroCAD 10.0
build 20, multiple chamber definitions can also be included in a single file,
thus reducing the number of files that are required to support some products.

To create a multi-size file, the data for all sizes is included in a single
file, with each size separated by a Size= line.  For example, multiple pipe
sizes could be defined with:

  Type=Pipe
  Size=10"
  Diam=10/12
  Size=12"
  Diam=1
  Size=18"
  Diam=1.5
  etc.

When the size option is used, all sizes are assumed to be the same length,
otherwise you should specify a varying length at the top of the file with:

  MultiLength=True             (added in HydroCAD 10.0 build 23)

Starting with HydroCAD 10.0 build 25, the MultiLength option also supports
a variable chamber overlap, depending on the chamber size.

*********************** Hidden Chamber Definitions **********************

Starting with HydroCAD-10, chamber definitions can be marked with "Hidden=True"
to prevent them from appearing in chamber selection lists, while retaining the
file for backwards compatibility with previous HydroCAD projects.  This option
may be used when a chamber is discontinued and is no longer available for new
designs, or when a chamber definition has been superseded by a newer version.

*************************** Renaming Chambers *******************************

Prior to HydroCAD-10 build 20, renaming a chamber file typically required the
creation of a new chamber file together with hiding the old file.  Starting
with this build, a file can simply be renamed without having to retain the
original file.  This is accomplished by including a reference to the previous
file name inside the new chamber file, such as:

OldName=Acme Model 1A

Any references to Acme Model 1A will now be automatically filled by using the
new chamber definition.  This option can also be used within a Size section to
map an old file to a specific size within the new file.  Or an asterisk can be
added to map all previous Sizes sizes from a previous multi-size file into the
new multi-size chamber file:

OldName=Acme Model 1A,*


***************** Chamber Bedding, Cover and Spacing ********************

To allow automated chamber layout with HydroCAD-9 and later, the typical
requirements for chamber spacing, bedding, and cover can be specified with
the following statements:

  Spacing=  0.25  1.0  1.0   {row, side, end spacing}
  Bedding=  0.50  0.25       {bedding & cover}

Note that these are typical values, which the designer can override within
each project as required.  Since these values are applied to the overall
chamber dimensions (see above) an "Overall" statement may also be needed.

*********************** Category Statement ****************************

By default, all chamber definitions are available for automatic layout with
the chamber wizard.  If a specific chamber definition (such as a filter unit,
end-cap, or header) is not appropriate for use with the wizard, it can be
marked with an appropriate category statement, such as:

  Category=Filter

Any desired text can be used to indicate the reason for the exclusion. Only
chamber definitions WITHOUT a category statement will appear in the wizard.

********************** Envelope Terminology ***************************

By default, chambers are assumed to be embeded in an envelope of "Stone".
Starting with HydroCAD 10.0 build 25, this term can be customized by using
the 'Enevelope' statement:

  Envelope=Concrete  {specifies a Conrete envelope instead of Stone}

************************ Void Storage *********************************

The Chamber wizard normally allows for storage in the stone voids used as
backfill.  The exact percentage of voids is specified by the HydroCAD user.
For chamber products that do not allow for storage in the backfill
(such as non-perforated storwater tanks or concrete forms) the void storage
can be forced to zero by the following statement, implemented in HydroCAD
10.00 build 25:

  AllowVoids=False

************************ Common Pipe Shapes ****************************

HydroCAD-9 allows simplified chamber definitions for common pipe shapes,
including round, elliptical, arch, box, and crown-span.  Instead of providing
a table of Width or IncSect values, you specify actual pipe dimensions as
detailed below.

For round pipe:

  Type=Pipe      // Beginning of pipe data
  Diam=2.0       // Inside Diameter
  WallThick=0.3  // Wall thickness (only for concrete/thick-walled pipe)

For elliptical or arch-pipe:

  Type=Pipe      // Beginning of pipe data
  Width=5.416    // Inside width or span
  Height=3.33    // Inside height or rise
  Rtop=2.7833    // Top radius
  Rbot=7.7083    // Bottom radius
  Rcor=0.824     // Corner radius
  WallThick=0.5  // Wall thickness (only for concrete/thick-walled pipe)

For box pipe or crown-span:

  Type=Pipe      // Beginning of pipe data
  Width=12       // Inside width or span
  Height=4       // Inside height or rise
  Fillet=0.5     // Size of corner fillet(omit to exclude fillet)
  WallThick=0.5  // Wall thickness
  TopThick=0.6   // Top thickness (if different than WallThick)
  BotThick=0.4   // Bottom thickness (if different then WallThick)

HydroCAD 10.0 build 4 adds built-in support for single-wall corrugated pipe:

  Type=Pipe           // Beginning of pipe data
  Diam=2.0            // Inside Diameter
  WallThick=0.2 0.65  // Corrugation depth and fraction of wall thickness falling inside the pipe

HydroCAD 10.0 build 15 extends this capability to double-wall corrugated pipe:

  Type=Pipe               // Beginning of pipe data
  Diam=2.0                // Inside Diameter
  WallThick=0.2  0  0.55  // Corrugation depth and fraction of wall thickness inside/outside pipe