Skip to main content

section_properties/
material.rs

1//! Isotropic linear-elastic material definition.
2//!
3//! All values in SI base units (Pa, kg/m³, /K).
4use std::fmt;
5
6#[derive(Debug, Clone, Copy, PartialEq)]
7pub struct Material {
8    /// Young's modulus `Pa`
9    pub youngs_modulus: f64,
10    /// Shear modulus `Pa`
11    pub shear_modulus: f64,
12    /// Poisson's ratio [-]
13    pub poissons_ratio: f64,
14    /// Density [kg/m³]
15    pub density: f64,
16    /// Coefficient of thermal expansion [1/K]
17    pub thermal_expansion: f64,
18    /// Yield strength `Pa` (for plastic analysis)
19    pub yield_strength: f64,
20    /// Ultimate tensile strength `Pa`
21    pub ultimate_strength: f64,
22    /// Optional: identifier/name for display
23    pub name: &'static str,
24    /// Optional: color for visualization (RGB 0-255)
25    pub color: Option<(u8, u8, u8)>,
26}
27
28impl Material {
29    /// Create a new material from E and ν (computes G = E / (2(1+ν))).
30    ///
31    /// This is an **unchecked constructor** — it does not validate the
32    /// inputs.  Call [`is_valid`](Self::is_valid) to verify that the
33    /// resulting material has physically admissible properties.
34    pub fn new(youngs_modulus: f64, poissons_ratio: f64, density: f64, name: &'static str) -> Self {
35        let shear_modulus = youngs_modulus / (2.0 * (1.0 + poissons_ratio));
36        Self {
37            youngs_modulus,
38            shear_modulus,
39            poissons_ratio,
40            density,
41            thermal_expansion: 0.0,
42            yield_strength: 0.0,
43            ultimate_strength: 0.0,
44            name,
45            color: None,
46        }
47    }
48
49    /// Create a new material with all properties specified.
50    ///
51    /// This is an **unchecked constructor** — it does not validate the
52    /// inputs.  Call [`is_valid`](Self::is_valid) to verify that the
53    /// resulting material has physically admissible properties.
54    pub fn with_all(
55        youngs_modulus: f64,
56        shear_modulus: f64,
57        poissons_ratio: f64,
58        density: f64,
59        thermal_expansion: f64,
60        yield_strength: f64,
61        ultimate_strength: f64,
62        name: &'static str,
63    ) -> Self {
64        Self {
65            youngs_modulus,
66            shear_modulus,
67            poissons_ratio,
68            density,
69            thermal_expansion,
70            yield_strength,
71            ultimate_strength,
72            name,
73            color: None,
74        }
75    }
76
77    /// Set thermal expansion coefficient.
78    pub fn with_thermal_expansion(mut self, alpha: f64) -> Self {
79        self.thermal_expansion = alpha;
80        self
81    }
82
83    /// Set yield strength.
84    pub fn with_yield_strength(mut self, fy: f64) -> Self {
85        self.yield_strength = fy;
86        self
87    }
88
89    /// Set ultimate strength.
90    pub fn with_ultimate_strength(mut self, fu: f64) -> Self {
91        self.ultimate_strength = fu;
92        self
93    }
94
95    /// Set visualization color (RGB).
96    pub fn with_color(mut self, r: u8, g: u8, b: u8) -> Self {
97        self.color = Some((r, g, b));
98        self
99    }
100
101    /// Get modular ratio relative to another material (n = E_this / E_ref).
102    pub fn modular_ratio(&self, ref_material: &Material) -> f64 {
103        self.youngs_modulus / ref_material.youngs_modulus
104    }
105
106    /// Check if material properties are physically valid.
107    ///
108    /// Returns `true` only when every field is finite and within the
109    /// physically admissible range for an isotropic linear-elastic solid:
110    ///
111    /// * `E > 0` and finite
112    /// * `G > 0` and finite
113    /// * `-1 < ν < 0.5` (strict on both sides: ν = -1 gives G = ∞,
114    ///   ν = 0.5 gives infinite bulk modulus)
115    /// * `ρ ≥ 0` and finite (zero density is admissible for a massless
116    ///   placeholder)
117    pub fn is_valid(&self) -> bool {
118        self.youngs_modulus.is_finite()
119            && self.youngs_modulus > 0.0
120            && self.shear_modulus.is_finite()
121            && self.shear_modulus > 0.0
122            && self.poissons_ratio.is_finite()
123            && self.poissons_ratio > -1.0
124            && self.poissons_ratio < 0.5
125            && self.density.is_finite()
126            && self.density >= 0.0
127    }
128}
129
130impl Default for Material {
131    /// Default to generic structural steel (S355).
132    fn default() -> Self {
133        presets::STEEL_S355
134    }
135}
136
137impl fmt::Display for Material {
138    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
139        write!(
140            f,
141            "{} (E={:.0} GPa, ν={:.2}, ρ={:.0} kg/m³)",
142            self.name,
143            self.youngs_modulus / 1e9,
144            self.poissons_ratio,
145            self.density
146        )
147    }
148}
149
150/// Common structural materials (SI units).
151pub mod presets {
152    use super::Material;
153
154    // Steel
155    /// Generic structural steel S235 (EN 10025)
156    pub const STEEL_S235: Material = Material {
157        youngs_modulus: 200e9,
158        shear_modulus: 76.923e9,
159        poissons_ratio: 0.3,
160        density: 7850.0,
161        thermal_expansion: 12e-6,
162        yield_strength: 235e6,
163        ultimate_strength: 360e6,
164        name: "S235",
165        color: Some((120, 120, 140)),
166    };
167
168    /// Generic structural steel S275 (EN 10025)
169    pub const STEEL_S275: Material = Material {
170        youngs_modulus: 200e9,
171        shear_modulus: 76.923e9,
172        poissons_ratio: 0.3,
173        density: 7850.0,
174        thermal_expansion: 12e-6,
175        yield_strength: 275e6,
176        ultimate_strength: 430e6,
177        name: "S275",
178        color: Some((130, 130, 150)),
179    };
180
181    /// Generic structural steel S355 (EN 10025) - most common
182    pub const STEEL_S355: Material = Material {
183        youngs_modulus: 200e9,
184        shear_modulus: 76.923e9,
185        poissons_ratio: 0.3,
186        density: 7850.0,
187        thermal_expansion: 12e-6,
188        yield_strength: 355e6,
189        ultimate_strength: 510e6,
190        name: "S355",
191        color: Some((140, 140, 160)),
192    };
193
194    /// Generic structural steel S460 (EN 10025)
195    pub const STEEL_S460: Material = Material {
196        youngs_modulus: 200e9,
197        shear_modulus: 76.923e9,
198        poissons_ratio: 0.3,
199        density: 7850.0,
200        thermal_expansion: 12e-6,
201        yield_strength: 460e6,
202        ultimate_strength: 620e6,
203        name: "S460",
204        color: Some((150, 150, 170)),
205    };
206
207    /// Stainless steel 304 (EN 1.4301)
208    pub const STAINLESS_304: Material = Material {
209        youngs_modulus: 193e9,
210        shear_modulus: 74.23e9,
211        poissons_ratio: 0.3,
212        density: 7930.0,
213        thermal_expansion: 17.2e-6,
214        yield_strength: 215e6,
215        ultimate_strength: 505e6,
216        name: "304 Stainless",
217        color: Some((180, 180, 190)),
218    };
219
220    /// Stainless steel 316 (EN 1.4401)
221    pub const STAINLESS_316: Material = Material {
222        youngs_modulus: 193e9,
223        shear_modulus: 74.23e9,
224        poissons_ratio: 0.3,
225        density: 7980.0,
226        thermal_expansion: 15.9e-6,
227        yield_strength: 205e6,
228        ultimate_strength: 515e6,
229        name: "316 Stainless",
230        color: Some((185, 185, 195)),
231    };
232
233    // Aluminum
234    /// Aluminum 6061-T6
235    pub const ALUMINUM_6061_T6: Material = Material {
236        youngs_modulus: 68.9e9,
237        shear_modulus: 26.0e9,
238        poissons_ratio: 0.33,
239        density: 2700.0,
240        thermal_expansion: 23.6e-6,
241        yield_strength: 276e6,
242        ultimate_strength: 310e6,
243        name: "6061-T6 Al",
244        color: Some((200, 200, 210)),
245    };
246
247    /// Aluminum 6063-T5
248    pub const ALUMINUM_6063_T5: Material = Material {
249        youngs_modulus: 68.3e9,
250        shear_modulus: 25.7e9,
251        poissons_ratio: 0.33,
252        density: 2700.0,
253        thermal_expansion: 23.4e-6,
254        yield_strength: 145e6,
255        ultimate_strength: 186e6,
256        name: "6063-T5 Al",
257        color: Some((205, 205, 215)),
258    };
259
260    /// Aluminum 7075-T6
261    pub const ALUMINUM_7075_T6: Material = Material {
262        youngs_modulus: 71.7e9,
263        shear_modulus: 26.9e9,
264        poissons_ratio: 0.33,
265        density: 2810.0,
266        thermal_expansion: 23.6e-6,
267        yield_strength: 503e6,
268        ultimate_strength: 572e6,
269        name: "7075-T6 Al",
270        color: Some((210, 210, 220)),
271    };
272
273    // Concrete
274    /// Concrete C25/30 (EN 1992)
275    pub const CONCRETE_C25_30: Material = Material {
276        youngs_modulus: 31e9,
277        shear_modulus: 12.9e9,
278        poissons_ratio: 0.2,
279        density: 2400.0,
280        thermal_expansion: 10e-6,
281        yield_strength: 25e6, // f_ck
282        ultimate_strength: 30e6,
283        name: "C25/30 Concrete",
284        color: Some((180, 170, 160)),
285    };
286
287    /// Concrete C30/37
288    pub const CONCRETE_C30_37: Material = Material {
289        youngs_modulus: 33e9,
290        shear_modulus: 13.75e9,
291        poissons_ratio: 0.2,
292        density: 2400.0,
293        thermal_expansion: 10e-6,
294        yield_strength: 30e6,
295        ultimate_strength: 37e6,
296        name: "C30/37 Concrete",
297        color: Some((175, 165, 155)),
298    };
299
300    /// Concrete C40/50
301    pub const CONCRETE_C40_50: Material = Material {
302        youngs_modulus: 35e9,
303        shear_modulus: 14.58e9,
304        poissons_ratio: 0.2,
305        density: 2450.0,
306        thermal_expansion: 10e-6,
307        yield_strength: 40e6,
308        ultimate_strength: 50e6,
309        name: "C40/50 Concrete",
310        color: Some((170, 160, 150)),
311    };
312
313    // Timber (GL24h)
314    /// Glued laminated timber GL24h (EN 14080).
315    ///
316    /// **G is an independently specified engineering constant, NOT computed
317    /// from the isotropic relation** `G = E/(2(1+ν))`. Timber is orthotropic:
318    /// `E` is the mean modulus parallel to grain (`E₀,mean = 11.6 GPa`),
319    /// `G` is the mean shear modulus (`G,mean ≈ 0.725 GPa`), and `ν` is the
320    /// Poisson's ratio. The isotropic formula would give `G ≈ 4.30 GPa`,
321    /// which is ~6× too high and would produce incorrect torsional stiffness.
322    ///
323    /// Source: EN 14080:2013, GL24h strength class. The shear modulus value
324    /// (0.725 GPa) is consistent with the EN 14080 range (0.65–0.72 GPa)
325    /// used in timber engineering practice.
326    pub const TIMBER_GL24H: Material = Material {
327        youngs_modulus: 11.6e9,
328        shear_modulus: 0.725e9,
329        poissons_ratio: 0.35,
330        density: 420.0,
331        thermal_expansion: 5e-6,
332        yield_strength: 24e6, // f_m,k
333        ultimate_strength: 24e6,
334        name: "GL24h Timber",
335        color: Some((200, 170, 120)),
336    };
337
338    // Titanium
339    /// Titanium Grade 5 (Ti-6Al-4V)
340    pub const TITANIUM_GR5: Material = Material {
341        youngs_modulus: 113.8e9,
342        shear_modulus: 44.0e9,
343        poissons_ratio: 0.342,
344        density: 4430.0,
345        thermal_expansion: 8.6e-6,
346        yield_strength: 880e6,
347        ultimate_strength: 950e6,
348        name: "Ti-6Al-4V",
349        color: Some((160, 160, 170)),
350    };
351}
352
353/// Material group for composite sections (transformed section method).
354///
355/// Groups elements sharing the same material reference for stiffness assembly.
356#[derive(Debug, Clone, PartialEq)]
357pub struct MaterialGroup {
358    pub material: Material,
359    /// List of polygon indices belonging to this material group
360    pub polygon_indices: Vec<usize>,
361}
362
363impl MaterialGroup {
364    pub fn new(material: Material, polygon_indices: Vec<usize>) -> Self {
365        Self {
366            material,
367            polygon_indices,
368        }
369    }
370}
371
372#[cfg(test)]
373mod tests {
374    use super::presets::*;
375    use super::*;
376
377    #[test]
378    fn steel_material_properties() {
379        let mat = STEEL_S355;
380        assert!((mat.youngs_modulus - 200e9).abs() < 1e6);
381        assert!((mat.poissons_ratio - 0.3).abs() < 1e-9);
382        assert!(mat.is_valid());
383    }
384
385    #[test]
386    fn modular_ratio() {
387        let steel = STEEL_S355;
388        let concrete = CONCRETE_C30_37;
389        let n = steel.modular_ratio(&concrete);
390        assert!((n - 200.0 / 33.0).abs() < 0.1); // ≈ 6.06
391    }
392
393    #[test]
394    fn material_builder() {
395        let mat = Material::new(210e9, 0.3, 7850.0, "Custom Steel")
396            .with_yield_strength(400e6)
397            .with_color(255, 0, 0);
398        assert_eq!(mat.yield_strength, 400e6);
399        assert_eq!(mat.color, Some((255, 0, 0)));
400    }
401
402    /// Regression test: TIMBER_GL24H stores independently specified
403    /// engineering constants (orthotropic timber), NOT isotropic G.
404    ///
405    /// Timber is orthotropic — `G` is the mean shear modulus from EN 14080,
406    /// not `E/(2(1+ν))`. This test protects the intended values against
407    /// accidental "fixes" that would replace G with the isotropic relation.
408    #[test]
409    fn timber_gl24h_orthotropic_constants() {
410        let mat = TIMBER_GL24H;
411
412        // Exact values from EN 14080 GL24h.
413        assert!((mat.youngs_modulus - 11.6e9).abs() < 1e3, "E = 11.6 GPa");
414        assert!((mat.shear_modulus - 0.725e9).abs() < 1e3, "G = 0.725 GPa");
415        assert!((mat.poissons_ratio - 0.35).abs() < 1e-9, "nu = 0.35");
416        assert!((mat.density - 420.0).abs() < 1e-6, "rho = 420 kg/m³");
417
418        // G must NOT equal the isotropic relation E/(2(1+ν)).
419        let g_isotropic = mat.youngs_modulus / (2.0 * (1.0 + mat.poissons_ratio));
420        assert!(
421            (mat.shear_modulus - g_isotropic).abs() > 1e9,
422            "TIMBER_GL24H G ({:.3} GPa) must differ from isotropic G ({:.3} GPa)",
423            mat.shear_modulus / 1e9,
424            g_isotropic / 1e9
425        );
426
427        // Material must pass validation.
428        assert!(mat.is_valid(), "TIMBER_GL24H must be valid");
429    }
430}