# py-concrete-calc

[![PyPI version](https://img.shields.io/pypi/v/py-concrete-calc)](https://pypi.org/project/py-concrete-calc/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Built by SlabCalc.co](https://img.shields.io/badge/Built%20by-SlabCalc.co-orange)](https://www.slabcalc.co)

**Concrete volume, bag, material, and cost calculations for construction projects.**

A Python library for estimating concrete quantities — from simple slab volumes to full project takeoffs with rebar, wire mesh, formwork, and regional pricing. Built by [SlabCalc.co](https://www.slabcalc.co), the free online concrete calculator.

---

## Installation

```bash
pip install py-concrete-calc
```

For pandas DataFrame support:

```bash
pip install py-concrete-calc[pandas]
```

## Quick Start

```python
from concrete_calc import estimate, inches_to_feet

# 20 ft × 10 ft slab, 4 inches thick
result = estimate(length=20, width=10, thickness=inches_to_feet(4))

print(f"Volume: {result.cubic_yards} cubic yards")
print(f"80 lb bags needed: {result.bags}")
print(f"Ready-mix cost: ${result.ready_mix_cost_total}")
print(f"Bag cost: ${result.bag_cost_total}")
```

### Full project estimate with materials

```python
from concrete_calc import estimate, inches_to_feet

result = estimate(
    length=20,
    width=10,
    thickness=inches_to_feet(4),
    waste_factor=1.10,       # 10% extra for waste
    include_materials=True,  # adds rebar, wire mesh, forms
    rebar_spacing_in=12,     # 12" on-center
    rebar_bar_size=4,        # #4 rebar
)

print(f"Concrete: {result.cubic_yards} yd³")
print(f"Rebar: {result.rebar['pieces_20ft']} pieces (20 ft bars)")
print(f"Wire mesh: {result.wire_mesh['sheets_5x10']} sheets")
print(f"Form boards: {result.forms['boards_8ft']} boards (8 ft)")
```

### Using the ConcreteCalculator class

```python
from concrete_calc import ConcreteCalculator

calc = ConcreteCalculator()

# Volumes for different shapes
print(calc.slab(20, 10, 0.333))          # rectangular slab
print(calc.cylinder(diameter=2, height=4)) # sonotube column
print(calc.footing(30, 1.5, 1))           # continuous footing
print(calc.stairs(0.75, 1.0, 3.0, 5))     # 5-step staircase
print(calc.wall(20, 8, 0.5))              # concrete wall
print(calc.circular_slab(10, 0.333))       # round pad
```

## Shape Calculators

All shape functions accept dimensions in consistent units (feet or meters) and return volume in cubic units.

| Function | Description | Online Calculator |
|---|---|---|
| `slab(l, w, t)` | Rectangular slab | [Slab Calculator](https://www.slabcalc.co/calculators/concrete-slab-calculator) |
| `cylinder(d, h)` | Round column / sonotube | [Column Calculator](https://www.slabcalc.co/calculators/concrete-column-calculator) |
| `footing(l, w, d)` | Continuous footing | [Footing Calculator](https://www.slabcalc.co/calculators/concrete-footing-calculator) |
| `stairs(rise, run, w, n)` | Staircase | [Stairs Calculator](https://www.slabcalc.co/calculators/concrete-stairs-calculator) |
| `curb(l, w, h)` | Curb / barrier | [Curb Calculator](https://www.slabcalc.co/calculators/concrete-curb-calculator) |
| `wall(l, h, t)` | Concrete wall | [Wall Calculator](https://www.slabcalc.co/calculators/concrete-wall-calculator) |
| `hollow_cylinder(od, id, h)` | Hollow column | — |
| `circular_slab(d, t)` | Round pad / fire pit | — |
| `triangular_prism(b, h, l)` | Ramp / tapered edge | — |
| `grade_beam(l, w, d, n)` | Grade beam | — |

## Bag Estimation

```python
from concrete_calc import bag_estimate, bags_from_yards

bags = bag_estimate(cubic_feet=27, bag_size=80)  # 45 bags
bags = bags_from_yards(cubic_yards=1, bag_size=60)  # 60 bags
```

Supports 40, 50, 60, and 80 lb bags. For a visual breakdown, see [How Many Bags of Concrete Do I Need?](https://www.slabcalc.co/articles/how-many-bags-of-concrete-do-i-need)

## Cost Estimation

```python
from concrete_calc import ready_mix_cost, bag_cost

# Ready-mix truck delivery
r = ready_mix_cost(cubic_yards=5, price_per_yard=160)
print(f"${r['cost']}")  # $800.00

# Bagged concrete from the hardware store
b = bag_cost(cubic_feet=27, bag_size=80, price_per_bag=6.50)
print(f"{b['bags']} bags = ${b['cost']}")  # 45 bags = $292.50
```

For current pricing in your area, check the [Concrete Cost Calculator](https://www.slabcalc.co/calculators/concrete-cost-calculator).

### Regional Pricing Database

```python
from concrete_calc import get_regional_price, list_regions

print(list_regions())
# ['midwest', 'national', 'northeast', 'southeast', 'southwest', 'west']

ne = get_regional_price("northeast")
print(f"Northeast: ${ne['price_per_yard']}/yd³")  # $175.00/yd³
```

## Material Quantities

```python
from concrete_calc import rebar_estimate, wire_mesh_estimate, form_lumber_estimate

# Rebar grid for a 20×10 ft slab
rebar = rebar_estimate(20, 10, spacing_in=12, bar_size=4)
print(f"{rebar['pieces_20ft']} bars, {rebar['weight_lbs']} lbs")

# Welded wire mesh
mesh = wire_mesh_estimate(20, 10)
print(f"{mesh['sheets_5x10']} sheets (5×10 ft)")

# Perimeter forms
forms = form_lumber_estimate(20, 10)
print(f"{forms['boards_8ft']} boards, {forms['stakes']} stakes")
```

## Unit Conversions

```python
from concrete_calc import (
    cubic_feet_to_yards,
    cubic_yards_to_cubic_feet,
    cubic_feet_to_meters,
    cubic_meters_to_yards,
    inches_to_feet,
    cm_to_meters,
)

cubic_feet_to_yards(27)       # 1.0
inches_to_feet(4)             # 0.333...
cm_to_meters(10)              # 0.1
```

## Export Results

```python
from concrete_calc import estimate, inches_to_feet, to_json, to_csv

r = estimate(20, 10, inches_to_feet(4))

# JSON
print(to_json(r))

# CSV (multiple estimates)
projects = [
    estimate(20, 10, inches_to_feet(4)),
    estimate(30, 12, inches_to_feet(6)),
]
print(to_csv(projects))
```

### Pandas Integration

```python
from concrete_calc import estimate, inches_to_feet
from concrete_calc.export import to_dataframe

projects = [
    estimate(20, 10, inches_to_feet(4)),
    estimate(30, 12, inches_to_feet(6)),
    estimate(15, 15, inches_to_feet(4)),
]

df = to_dataframe(projects)
print(df[["cubic_yards", "bags", "ready_mix_cost_total"]])
```

## Jupyter Notebook Example

```python
# Cell 1: Install
# !pip install py-concrete-calc

# Cell 2: Quick slab estimate
from concrete_calc import ConcreteCalculator, inches_to_feet

calc = ConcreteCalculator()

# Garage slab: 24 ft × 24 ft × 4 in
thickness = inches_to_feet(4)
result = calc.estimate(24, 24, thickness, include_materials=True)

print("=== Garage Slab Estimate ===")
print(f"Concrete: {result.cubic_yards} cubic yards")
print(f"80 lb bags: {result.bags}")
print(f"Ready-mix cost: ${result.ready_mix_cost_total:,.2f}")
print(f"Bag cost: ${result.bag_cost_total:,.2f}")
print(f"Rebar (20ft bars): {result.rebar['pieces_20ft']}")
print(f"Wire mesh sheets: {result.wire_mesh['sheets_5x10']}")
print(f"Form boards (8ft): {result.forms['boards_8ft']}")

# Cell 3: Compare multiple projects
from concrete_calc.export import to_dataframe

projects = [
    calc.estimate(10, 10, inches_to_feet(4), include_materials=True),
    calc.estimate(20, 10, inches_to_feet(4), include_materials=True),
    calc.estimate(24, 24, inches_to_feet(4), include_materials=True),
    calc.estimate(30, 30, inches_to_feet(6), include_materials=True),
]

df = to_dataframe(projects)
df.index = ["Small patio", "Walkway", "Garage", "Large slab"]
print(df[["cubic_yards", "bags", "bag_cost_total", "ready_mix_cost_total"]])
```

## Common Projects Reference

| Project | Typical Size | Calculator |
|---|---|---|
| Sidewalk | 4 ft × 20 ft × 4 in | [Slab Calculator](https://www.slabcalc.co/calculators/concrete-slab-calculator) |
| Patio | 12 ft × 12 ft × 4 in | [Slab Calculator](https://www.slabcalc.co/calculators/concrete-slab-calculator) |
| Garage floor | 24 ft × 24 ft × 4 in | [Slab Calculator](https://www.slabcalc.co/calculators/concrete-slab-calculator) |
| Driveway | 10 ft × 20 ft × 5 in | [Slab Calculator](https://www.slabcalc.co/calculators/concrete-slab-calculator) |
| Deck footing | 12 in dia × 48 in deep | [Column Calculator](https://www.slabcalc.co/calculators/concrete-column-calculator) |
| Fence post | 8 in dia × 24 in deep | [Column Calculator](https://www.slabcalc.co/calculators/concrete-column-calculator) |
| House footing | 20 ft × 18 in × 12 in | [Footing Calculator](https://www.slabcalc.co/calculators/concrete-footing-calculator) |
| Retaining wall | 20 ft × 4 ft × 8 in | [Wall Calculator](https://www.slabcalc.co/calculators/concrete-wall-calculator) |

## API Reference

Full API documentation is available inline via docstrings. Use `help(function_name)` in Python or your IDE's autocomplete.

For interactive calculators with visual breakdowns, visit [SlabCalc.co](https://www.slabcalc.co).

## License

[MIT](LICENSE) — Built by [SlabCalc.co](https://www.slabcalc.co)
