calculiva

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 4, 2026 License: MIT Imports: 1 Imported by: 0

README

calculiva-go

Home improvement estimators from calculiva.com, as a Go module: mulch, topsoil and fill, sod and hot mix asphalt.

This module is a line-by-line port of the engine that runs the calculators on the site. The test vectors of the site are reproduced as Go tests, with the same inputs, the same expected outputs and the same tolerances, except where a value of a commercial publisher was replaced by a synthetic test value labelled as such.

go get github.com/calculiva/calculiva-go

Go 1.21 or later. No dependency outside the standard library.

What this module is, and is not

Calculiva is a data house, not a trade. Nobody here claims to be a landscaper or a paver. What the module offers is arithmetic you can check and constants you can trace:

  • every business constant shipped (a pallet size, a CPSC depth, a sale unit) is a named Go constant or variable whose documentation gives the id of its data sheet, the public source it was read on and the date it was verified;
  • the values of commercial publishers whose terms do not allow reproduction (material and asphalt unit weights, bag and wheelbarrow sizes, sod allowances, asphalt lift rules) are not shipped: they are inputs of the user, with no default. The sources Calculiva read are listed at https://calculiva.com/data-sources/;
  • nothing is rounded or invented to fill a gap: when a source is silent, the value is absent (a nil pointer or a nil slice, never a placeholder number);
  • the results are planning quantities. The manufacturer's instructions, the local code and the installer on site govern.

All lengths are millimetres (calculiva.Inch = 25.4, calculiva.Foot = 304.8). Invalid input returns a *calculiva.InputError that names the offending field.

Example

package main

import (
	"fmt"

	calculiva "github.com/calculiva/calculiva-go"
	"github.com/calculiva/calculiva-go/mulch"
)

func main() {
	// Two 40 x 3 ft beds topped up from 1 in to 3 in, bought in 2 cu ft bags.
	bed := mulch.Area{
		ID:       "front-bed",
		Kind:     mulch.Bed{L: 40 * calculiva.Foot, W: 3 * calculiva.Foot, Count: 2},
		Target:   3 * calculiva.Inch,
		Existing: 1 * calculiva.Inch,
	}
	input := mulch.Input{Areas: []mulch.Area{bed}, BagSize: 2}

	plan, err := mulch.NewPlan(input, mulch.NewRules())
	if err != nil {
		fmt.Println(err)
		return
	}
	// 240 sq ft at 2 in.
	fmt.Printf("%.1f cu ft, %.0f bags\n", plan.Totals.CuFt, *plan.Buy.Bags)
	// 40.0 cu ft, 20 bags
}

Packages and functions

Function What it does Calculator
mulch.NewRules Builds the mulch rules: Penn State maximum depths, CPSC 324/325 playground rules. Mulch calculator
mulch.NewPlan Volume per bed, tree ring, known area, play structure or swing; bags, bulk, break-even, loads, warnings. Mulch calculator
mulch.NewRingGuidance Published trunk gaps and minimum ring radii, publisher by publisher. Mulch calculator
mulch.CheckRing A tree ring against every published gap and radius. Mulch calculator
mulch.Coverage Square feet per bag at each depth, bags per cubic yard. Mulch calculator
soil.NewRules Builds the soil rules: NIST sale units, with the loose and bank weights entered by the user. Soil calculator
soil.NewPlan Topsoil and fill by area: volume, bags, bulk by the yard or the ton, weight, trips, wheelbarrow loads. Soil calculator
soil.AreaOf Area of a rectangle, circle, triangle or known area. Soil calculator
soil.BagCuFt Bag volume in cubic feet from cubic feet, U.S. dry quarts or litres. Soil calculator
soil.Coverage Square feet covered per cubic yard, per ton and per cubic foot at each depth. Soil calculator
sod.NewRules Builds the sod rules: surveyed formats and pallets, soil preparation, UF/IFAS plugs; the allowances are entered by the user. Sod calculator
sod.NewPlan Pieces per area (rectangles laid out piece by piece), pallets, plugs, soil preparation, cost, weight. Sod calculator
sod.LayRect Staggered layout of one rectangle with offcut pairing and strip grouping. Sod calculator
sod.FormatTable Pieces per pallet coverage and per lawn for each format. Sod calculator
asphalt.NewRules Builds the asphalt rules: pounds per short ton (NIST); the water unit weight, lift rules and references are entered by the user. Asphalt calculator
asphalt.NewPlan Tons by zone and course, lifts under the roller, whole loads, cost, reference spread. Asphalt calculator
asphalt.ZoneArea Area of a rectangle, flare (trapezoid) or disc fraction. Asphalt calculator
asphalt.UnitWeightOf In-place unit weight (a required input), entered or from the Rice value and compaction. Asphalt calculator
asphalt.RicePCF Rice value (maximum theoretical specific gravity) x compaction x unit weight of water, all entered by the user. Asphalt calculator
asphalt.CoverageTable Square feet and yards covered by one ton at each thickness. Asphalt calculator
calculiva.ConstantsCSV The constants registry (one row per data sheet), embedded. Data sources

Data and licences

The code is under the MIT licence (LICENSE). The embedded registry data/calculiva-home-improvement-constants.csv, returned by calculiva.ConstantsCSV, is under Creative Commons Attribution 4.0 (data/LICENSE); credit "Calculiva" with a link to https://calculiva.com/.

Market surveys expire: each such constant documents its expiry date. Check it before relying on a price-sensitive or product-specific value.

Documentation

Overview

Package calculiva holds what the Calculiva home improvement estimators share: the length units, the input error type and the embedded constants registry.

The estimators themselves live in the sub-packages mulch, soil, sod and asphalt. They are a line-by-line port of the engine that runs the calculators on https://calculiva.com/ and their tests reproduce the test vectors of the site, with the same tolerances, except where a value of a commercial publisher was replaced by a synthetic test value labelled as such.

Calculiva is a data house, not a trade. Nobody here claims to be a landscaper or a paver. What the module offers is arithmetic you can check and constants you can trace:

  • every business constant shipped (a pallet size, a CPSC depth, a sale unit) is a named Go constant or variable whose documentation gives the id of its data sheet, the public source it was read on and the date it was verified;
  • the values of commercial publishers whose terms do not allow reproduction (material and asphalt unit weights, bag and wheelbarrow sizes, sod allowances, asphalt lift rules) are not shipped: they are inputs of the user, with no default. The sources Calculiva read are listed at https://calculiva.com/data-sources/;
  • nothing is rounded or invented to fill a gap: when a source is silent, the value is absent;
  • the results are planning quantities. The manufacturer's instructions, the local code and the installer on site govern.

All lengths are millimetres (Inch = 25.4, Foot = 304.8). Invalid input returns an *InputError that names the offending field.

The data sheets behind the constants are listed at https://calculiva.com/data-sources/ and the registry itself is returned by ConstantsCSV.

Index

Constants

View Source
const Foot float64 = 304.8

Foot is one foot in millimetres (exact by definition of the international foot).

View Source
const Inch float64 = 25.4

Inch is one inch in millimetres (exact by definition of the international inch).

Variables

This section is empty.

Functions

func ConstantsCSV

func ConstantsCSV() string

ConstantsCSV returns the Calculiva home improvement constants registry (CSV, UTF-8), licensed CC BY 4.0.

One row per data sheet: id, label, status, scope, source_name, source_url, verified_at, expires_at, sample_size.

Types

type InputError

type InputError struct {
	// Message is human-readable, in English.
	Message string
	// Field identifies the offending field (for example "a1-depth" or "bag").
	Field string
}

InputError is an invalid input, with the name of the field that caused it.

func (*InputError) Error

func (e *InputError) Error() string

Error returns the message followed by the field in parentheses.

Directories

Path Synopsis
Package asphalt estimates hot mix asphalt by zone and by course.
Package asphalt estimates hot mix asphalt by zone and by course.
internal
num
Package num holds the number helpers shared by the estimators: tolerant rounding, range checks and the number formats used in error messages.
Package num holds the number helpers shared by the estimators: tolerant rounding, range checks and the number formats used in error messages.
Package mulch estimates mulch by area: beds, tree rings, known areas, play structures and swings (CPSC).
Package mulch estimates mulch by area: beds, tree rings, known areas, play structures and swings (CPSC).
Package sod estimates sod by area: staggered layout of rectangles with offcut reuse, areas by square footage with an allowance, plugs (UF/IFAS Table 3), soil preparation, pallets, cost and weight.
Package sod estimates sod by area: staggered layout of rectangles with offcut reuse, areas by square footage with an allowance, plugs (UF/IFAS Table 3), soil preparation, pallets, cost and weight.
Package soil estimates topsoil and fill dirt by area: volume, bags, bulk, weight and hauling.
Package soil estimates topsoil and fill dirt by area: volume, bags, bulk, weight and hauling.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL