API

geometry Module

This module provides classes and functions to manage timber sections and their geometric properties.

Classes

ShapeType: Enum class defining section type string constants.

TimberSection: A class is used to manage timber section attributes.

RectangleShape: Represents structural section properties for a rectangular cross-section.

TimberShape: An alias for the RectangleShape class.

Functions

import_section_library(): Returns a DataFrame containing the section library defined in timberas/data/section_library.csv

Classes

ShapeType

Bases: str, Enum

An enumeration of section type string constants. Provides a type-safe way of representing different section types.

Attributes:
  • SINGLE_BOARD (str) –

    Represents a section composed of a single board, e.g. 90x35

  • MULTI_BOARD (str) –

    Represents a section composed of multiple boards, e.g. 2/90x35

  • ROUND (str) –

    Represents a round section (unused)

TimberSection dataclass

Calculates geometric and structural section properties from cross-section parameters. Selects shape class from shape_type to calculate: A_g, A_t, A_c, I_x, I_y. Class properties Z_x, Z_y, b_tot, and A_s calculated as derived attributes.

Attributes:
  • shape_type (ShapeType | str) –

    The type of the section shape.

  • b (float) –

    The breadth of the section.

  • d (float) –

    The depth of the section.

  • n (int) –

    The number of members in the section. Default = 1.

  • name (str) –

    The name of the section. Defaults to an empty string.

  • shape (TimberShape) –

    The shape of the section, calculated after initialization.

  • A_g (float) –

    The gross area of the section, calculated after shape is solved.

  • A_t (float) –

    The tensile area of the section, calculated after shape is solved.

  • A_c (float) –

    The compressive area of the section, calculated after shape is solved.

  • I_x (float) –

    The moment of inertia about the x-axis, calculated after shape is solved.

  • I_y (float) –

    The moment of inertia about the y-axis, calculated by shape if not provided.

  • sig_figs (int) –

    Number of significant figures to round calaculated values to.
Attributes
b_tot property 
b_tot: float

total width of section containing one or multiple boards, b_tot = n x b

Z_x property 
Z_x: float

Section modulus about x-axis.

Z_y property 
Z_y: float

Section modulus about y-axis. NOTE: Z for block section uses b_tot (n x b), but k12 stability factor uses b.

A_s property 
A_s: float

shear plane area 3.2.5

Functions
solve_shape 
solve_shape()

Sets shape class based on shape_type and recalculates relevant section properties.

from_dict classmethod 
from_dict(input_dict, solve_me=True)

Create a TimberSection by directly populating attributes from input dictionary, ignoring dictionary keys which aren't class attributes.

Parameters:
  • input_dict (dict) –

    Defines timber material data to be added, keys corresponding to class

  • solve_me (bool) –

    If True will run solve_shape() after attributes are added
Returns:
from_library classmethod 
from_library(name, library=None)

Creates a TimberSection object from a material library (DataFrame).

Parameters:
  • name (str) –

    The name of the timber material to lookup in the library (in 'name' column)

  • library (pd.DataFrame) –

    DataFrame containing a library of timber materials. If not provided, the default section library is used from import_section_library.
Returns:
  • TimberMaterial –

    The timber material object.

RectangleShape dataclass

Dataclass representing structural section properties for a rectangular cross-section. Class properties A_g, I_x, and I_y calculated as derived attributes.

Attributes:
  • d (float) –

    The height of the rectangle.

  • b (float) –

    The breadth (or width) of the rectangle.
Attributes
A_g property 
A_g: float

Gross area

I_x property 
I_x: float

Moment of inertia - major axis

I_y property 
I_y: float

Moment of inertia - minor axis

Functions

import_section_library 

import_section_library()

Imports a section library from a CSV file.

The CSV file is located at 'timberas/data/section_library.csv'.

Returns:
  • pd.DataFrame –

    pd.DataFrame: A DataFrame containing the contents of the section library CSV file.
Raises:
  • FileNotFoundError –

    If the CSV file does not exist.

material Module

This module provides classes and functions for creating timber materials described in AS1720.1.

Classes

GradeType: Enum class defining material grade string constants.

TimberMaterial: Represents a timber material based on AS1720.

Functions

import_material_library(): Returns a DataFrame containing the material library defined in timberas/data/material_library.csv

Classes

GradeType

Bases: str, Enum

An enumeration of grade type string constants. Provide a type-safe way of representing different grade types.

Attributes:
  • F_GRADE (str) –

    Represents the "F" grade type

  • MGP (str) –

    Represents the "MGP" grade type

  • GLULAM (str) –

    Represents the "GL" grade type

  • A_GRADE (str) –

    Represents the "A" grade type

TimberMaterial dataclass

Represents timber material properties as defined in AS1720.

Attributes:
  • name (str) –

    The name of the timber material.

  • grade (str) –

    The grade of the timber material

  • seasoned (bool) –

    A boolean indicating whether the timber material is seasoned.

  • grade_type (str) –

    The type of the timber grade, e.g F, MGP, GL.

  • f_b (float) –

    Material characteristic strength in bending.

  • f_t (float) –

    Material characteristic strength in tension.

  • f_s (float) –

    Material characteristic strength in shear.

  • f_c (float) –

    Material characteristic strength in compression.

  • E (float) –

    Material Modulus of Elasticity.

  • G (float) –

    Material Modulus of Rigidity.

  • density (float) –

    Material density.

  • phi_1 (float) –

    Capacity factor for the material for application category one.

  • phi_2 (float) –

    Capacity factor for the material for application category two.

  • phi_3 (float) –

    Capacity factor for the material for application category three.
Functions
phi 
phi(application_cat)

Returns the appropriate capacity factor for the given application category.

Parameters:
  • application_cat (int) –

    The application category.
Returns:
  • float( float ) –

    The capacity factor for the given application category.
Raises:
  • ValueError –

    If the application category is not recognized.
update_from_section_size 
update_from_section_size(d, b=None)

Updates the f_t property for large sections, including: f_t, f_b, f_c, f_s for MGP sections with d>140mm (AS1720.1 Table H3.1, Note 4); f_b for F-grade sections with d > 300mm (AS1720.1 Table H2.1 Note 1); f_t for F-grade sections with d > 150mm (AS1720.1 Table H.2 Note 2); f_t for Glulam sections with d > 150mm (AS1720.1 Table 7.1 Note 1).

Parameters:
  • d (float) –

    The depth of the timber section.

  • b (float | None) –

    The breadth of the timber section (required for A17 material).
from_dict classmethod 
from_dict(input_dict)

Create a TimberMaterial by directly populating attributes from input dictionary, ignoring dictionary keys which aren't class attributes.

Parameters:
  • input_dict (dict) –

    Key-value pairs to define the timber material, keys corresponding to class
Returns:
from_library classmethod 
from_library(name, library=None)

Creates a TimberMaterial object from a material library (DataFrame).

Parameters:
  • name (str) –

    The name of the timber material to lookup in the library (in 'name' column)

  • library (pd.DataFrame) –

    The DataFrame of the library of timber materials. If not provided, the default library MATERIAL_LIBRARY is used.
Returns:
  • TimberMaterial –

    The timber material object.

Functions

import_material_library 

import_material_library()

Imports a material library from a CSV file.

The CSV file is located at 'timberas/data/material_library.csv'.

Returns:
  • pd.DataFrame –

    pd.DataFrame: A DataFrame containing the contents of the material library CSV file.
Raises:
  • FileNotFoundError –

    If the CSV file does not exist.

member Module

TODO

Classes

EffectiveLengthFactor

Bases: float, Enum

Dataclass containing values for effective length factor g_13 for columns with intermediate lateral restraint. End restraint conditions as listed in Table 3.2, AS1720.1:2010.

Attributes:
  • FIXED_FIXED (float) –

    Both ends restrained in position and direction, g_13 = 0.7.

  • FIXED_PINNED (float) –

    One end restrained in position and direction, other in position only, g_13 = 0.85

  • PINNED_PINNED (float) –

    Both ends restrained in position only, g_13 = 1.

  • FIXED_SWAY (float) –

    One end restrained in position and direction, other in partial direction

  • FIXED_FREE (float) –

    One end restrained in position and direction, other unrestrained,

  • FLAT_END_RESTRAINT (float) –

    Flat ends, g_13 = 0.7

  • BOLTED_END_RESTRAINT (float) –

    Both ends held by bolts giving substantial restraint,

  • FRAMING_STUDS (float) –

    Studs in light framing, slight end restraint, g_13 = 0.9.

ApplicationCategory

Bases: IntEnum

Table 2.1, AS1720.1:2010

DurationFactorStrength

Bases: float, Enum

Table 2.3, Table G1?, AS1720.1:2010

RestraintEdge

Bases: str, Enum

compression edge is critical edge

TimberMember dataclass

TODO

Attributes
phi property 
phi: float

Table 2.1, AS1720.1:2010

S1 property 
S1: float

Slenderness coefficient for lateral buckling under bending, major axis. Clause 3.2.3, AS1720.1:2010. Not implemented in TimberMember parent class, added in child classes.

S2 property 
S2: float

Slenderness coefficient for lateral buckling under bending, minor axis. Clause 3.2.3(c), AS1720.1:2010.

S3 property 
S3: float

Slenderness coefficient for lateral buckling under compression, x axis. Clause 3.3.2, AS1720.1:2010. Not implemented in TimberMember parent class, added in child classes.

S4 property 
S4: float

Clause 3.3.2.2(b), AS1720.1:2010

rho_c property 
rho_c: float

Section E2, AS1720.1:2010

g_13_x property 
g_13_x: float

Effective length factor for compressive buckling, x-axis

g_13_y property 
g_13_y: float

Effective length factor for compressive buckling, y-axis

L_ax property 
L_ax: float

distance between effective lateral restraint against buckling about x-axis.

L_ay property 
L_ay: float

distance between effective lateral restraint against buckling about y-axis.

L_a_phi property 
L_a_phi: float

distance between effective torsional restraint against buckling, Cl 3.2.3.2(b).

rho_b property 
rho_b: float

Section E2, AS1720.1:2010

L_CLR property 
L_CLR: float

Clause

k_4 property 
k_4: float

Table 2.5, AS1720.1:2010

k_6 property 
k_6: float

Clause 2.4.3, AS1720.1:2010

k_9 property 
k_9: float

Modification factor for strength sharing. Clause 2.4.5.3, AS1720.1:2010. Not Implemented in TimberMember parent class, added in child classes.

k_12_c property 
k_12_c: float

Modification factor for stability, to allow for slenderness effects on compression strength. Minimum of k_12_x and k_12_y. Clause 3.3.3, AS1720.1:2010.

k_12_x property 
k_12_x: float

Modification factor for stability, to allow for slenderness effects on compression strength (x-axis). Clause 3.3.3, AS1720.1:2010.

k_12_y property 
k_12_y: float

Modification factor for stability, to allow for slenderness effects on compression strength (y-axis). Clause 3.3.3, AS1720.1:2010.

k_12_bend property 
k_12_bend: float

Modification factor for stability, to allow for slenderness effects on bending strength. Clause 3.2.4, AS1720.1:2010.

Functions
solve_capacities 
solve_capacities()

Calculate tension, compression, and bending design capacities.

update_k_1 
update_k_1(k_1)

Change k_1 factor and recalculate section capacities.

_N_dcx 
_N_dcx()

Clause 3.3.1.1, AS1720.1:2010

_N_dcy 
_N_dcy()

Clause 3.3.1.1, AS1720.1:2010

_N_dc 
_N_dc()

Clause 3.3.1.1, AS1720.1:2010

_N_dt 
_N_dt()

Clause 3.4.1, AS1720.1:2010

_M_d 
_M_d()

Clause 3.2.1.1, AS1720.1:2010

_V_d 
_V_d()

flexural shear strength Cl 3.2.5

k_6_lookup 
k_6_lookup(seasoned, high_temp_latitude)

Modification factor for strength for the effect of temperature. Clause 2.4.3, AS1720.1:2010.

calc_k12_compression 
calc_k12_compression(rho_c, S3)

Calculate stability factor k12 for compression. Clause 3.3.3, AS 1720.1:2010.

calc_k12_bending 
calc_k12_bending(rho_b, S1)

Calculate stability factor k12 for bending. Clause 3.2.4, AS1720.1:2010

RectangleMemberStabilityMixin

TODO

Attributes
S1 property 
S1: float

Clause (b), AS1720.1:2010

S3 property 
S3: float

Slenderness coefficient for buckling about x axis in rectangular sections. Clause 3.3.2.2(a), AS1720.1:2010.

L_CLR property 
L_CLR: float

3.2.3.2

BoardMember

Bases: RectangleMemberStabilityMixin, TimberMember

TODO

Attributes
k_9 property 
k_9: float

Clause 2.4.5.3, AS1720.1:2010

g_31 property 
g_31: float

Table 2.7, AS1720.1:2010

g_32 property 
g_32: float

Table 2.7, AS1720.1:2010

Functions
g3_lookup staticmethod 
g3_lookup(n)

Table 2.7, AS1720.1:2010

GlulamMember

Bases: RectangleMemberStabilityMixin, TimberMember

TODO

Attributes
k_9 property 
k_9: float

TODO

Functions