| name | ifc-syntax-materials |
| description | Use when you need to assign, read, or debug materials on IFC elements : a plain named material, a layered build-up for a wall or slab, a profiled cross-section for a beam or column, a constituent set for a window or door, or material properties. Prevents the most common material errors : attaching a layer-set or profile-set usage to a type object instead of an occurrence, manually serializing the derived TotalThickness, writing IfcMaterialList in a new IFC4 file, and using the deleted IFC2x3 material-property subtypes. Covers IfcMaterial, IfcRelAssociatesMaterial, the IfcMaterialSelect abstraction, the layered family (IfcMaterialLayerSet / IfcMaterialLayer / IfcMaterialLayerSetUsage), the profiled family (IfcMaterialProfileSet / IfcMaterialProfile / IfcMaterialProfileSetUsage / IfcCardinalPointReference), the constituent family (IfcMaterialConstituentSet / IfcMaterialConstituent), legacy IfcMaterialList, IfcMaterialProperties, and IFC2x3 / IFC4 / IFC4.3 version differences. Keywords: IFC materials, IfcMaterial, IfcRelAssociatesMaterial, IfcMaterialSelect, IfcMaterialLayerSet, IfcMaterialLayer, IfcMaterialLayerSetUsage, IfcMaterialProfileSet, IfcMaterialProfile, IfcMaterialProfileSetUsage, IfcCardinalPointReference, IfcMaterialConstituentSet, IfcMaterialConstituent, IfcMaterialList, IfcMaterialProperties, TotalThickness, layered wall, multi-layer wall, beam profile material, window frame material, how do I assign a material, why is my material on the type not the wall, material missing in viewer, IFC2x3, IFC4, IFC4.3.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
IFC Syntax : Materials
IFC carries the material of an element with two parts : a material definition
(what the element is made of) and an objectified relationship
(IfcRelAssociatesMaterial) that binds that definition to one or more elements.
The material definition is never a child of the element ; it floats in the file and
is linked.
This skill covers the plain IfcMaterial, the three structured material families
(layered, profiled, constituent), the legacy IfcMaterialList, and
IfcMaterialProperties.
Applies to IFC2x3, IFC4, and IFC4.3. The profiled and constituent families and
several attributes are IFC4 additions : see the Version Differences section.
Quick Reference
The association pattern
IfcRelAssociatesMaterial binds a material definition to elements. Verified verbatim
(IFC4.3) :
ENTITY IfcRelAssociatesMaterial
SUBTYPE OF (IfcRelAssociates);
RelatingMaterial : IfcMaterialSelect;
WHERE
AllowedElements : ...RelatedObjects restricted to IfcElement,
IfcElementType, IfcStructuralMember, IfcPort;
NoVoidElement : RelatedObjects must not contain
IfcFeatureElementSubtraction or IfcVirtualElement;
END_ENTITY;
RelatedObjects (SET [1:?] OF IfcDefinitionSelect, inherited from
IfcRelAssociates) : the elements or element types receiving the material.RelatingMaterial (IfcMaterialSelect) : the material definition assigned.
ALWAYS share one IfcRelAssociatesMaterial across many objects when they take the
same material : RelatedObjects is a set. NEVER point RelatedObjects at an
IfcFeatureElementSubtraction (an opening) or an IfcVirtualElement : the
NoVoidElement rule rejects it.
IfcMaterialSelect
IfcMaterialSelect is the abstraction in RelatingMaterial. The assigned material is
not always a plain IfcMaterial :
IfcMaterialSelect (SELECT)
├── IfcMaterial one homogeneous substance
├── IfcMaterialLayerSet an ordered layer stack (for types)
├── IfcMaterialLayerSetUsage a positioned layer stack (for occurrences)
├── IfcMaterialProfileSet a set of cross-section profiles (for types) [IFC4+]
├── IfcMaterialProfileSetUsage a positioned profile set (for occurrences) [IFC4+]
├── IfcMaterialConstituentSet named composite parts [IFC4+]
└── IfcMaterialList a bare list of materials (legacy)
The two usage entities (IfcMaterialLayerSetUsage, IfcMaterialProfileSetUsage)
are restricted to element occurrences ; the bare set entities go on the
element type. See the set-on-type rule below.
IfcMaterial
Verified verbatim (IFC4.3) :
ENTITY IfcMaterial
SUBTYPE OF (IfcMaterialDefinition);
Name : IfcLabel;
Description : OPTIONAL IfcText;
Category : OPTIONAL IfcLabel;
INVERSE
HasRepresentation : SET [0:1] OF IfcMaterialDefinitionRepresentation FOR RepresentedMaterial;
IsRelatedWith : SET [0:?] OF IfcMaterialRelationship FOR RelatedMaterials;
RelatesTo : SET [0:1] OF IfcMaterialRelationship FOR RelatingMaterial;
END_ENTITY;
Name is required ; Description and Category are optional.Category is a broad grouping ('concrete', 'steel', 'aluminium').- In IFC2x3
IfcMaterial had only Name : Description and Category are
IFC4 additions.
Layered materials : walls, slabs, roofs, plates
IfcMaterialLayerSet is the ordered stack ; IfcMaterialLayer is one layer ;
IfcMaterialLayerSetUsage positions the stack relative to the element.
ENTITY IfcMaterialLayerSet
SUBTYPE OF (IfcMaterialDefinition);
MaterialLayers : LIST [1:?] OF IfcMaterialLayer;
LayerSetName : OPTIONAL IfcLabel;
Description : OPTIONAL IfcText;
DERIVE
TotalThickness : IfcLengthMeasure := IfcMlsTotalThickness(SELF);
END_ENTITY;
TotalThickness is DERIVED : it is computed from the layer thicknesses by the
function IfcMlsTotalThickness. NEVER serialize a value for it.
ENTITY IfcMaterialLayer
SUBTYPE OF (IfcMaterialDefinition);
Material : OPTIONAL IfcMaterial;
LayerThickness : IfcNonNegativeLengthMeasure;
IsVentilated : OPTIONAL IfcLogical;
Name : OPTIONAL IfcLabel;
Description : OPTIONAL IfcText;
Category : OPTIONAL IfcLabel;
Priority : OPTIONAL IfcInteger;
WHERE
NormalizedPriority : NOT(EXISTS(Priority)) OR {0 <= Priority <= 100};
END_ENTITY;
LayerThickness is required. IsVentilated is TRUE for a ventilated air gap,
UNKNOWN for a non-ventilated air gap, FALSE for solid material.Priority (when present) MUST be in [0..100] (NormalizedPriority rule) ; it
governs which layer wins at element joints.IfcMaterialLayerSetUsage carries ForLayerSet, LayerSetDirection
(IfcLayerSetDirectionEnum : AXIS1 / AXIS2 / AXIS3), DirectionSense
(IfcDirectionSenseEnum : POSITIVE / NEGATIVE), OffsetFromReferenceLine
(IfcLengthMeasure), and optional ReferenceExtent.
In IFC2x3 IfcMaterialLayer had only Material, LayerThickness (typed
IfcPositiveLengthMeasure), and IsVentilated : Name, Description, Category,
and Priority are IFC4 additions, and LayerThickness was widened to
IfcNonNegativeLengthMeasure in IFC4.
Full layered-family signatures : see references/methods.md.
Profiled materials : beams, columns, members, piles (IFC4+)
The profiled family was introduced in IFC4 and does NOT exist in IFC2x3.
ENTITY IfcMaterialProfileSet
SUBTYPE OF (IfcMaterialDefinition);
Name : OPTIONAL IfcLabel;
Description : OPTIONAL IfcText;
MaterialProfiles : LIST [1:?] OF IfcMaterialProfile;
CompositeProfile : OPTIONAL IfcCompositeProfileDef;
END_ENTITY;
ENTITY IfcMaterialProfile
SUBTYPE OF (IfcMaterialDefinition);
Name : OPTIONAL IfcLabel;
Description : OPTIONAL IfcText;
Material : OPTIONAL IfcMaterial;
Profile : IfcProfileDef;
Priority : OPTIONAL IfcInteger;
Category : OPTIONAL IfcLabel;
WHERE
NormalizedPriority : NOT(EXISTS(Priority)) OR {0 <= Priority <= 100};
END_ENTITY;
Profile (IfcProfileDef) is the required cross-section. See
ifc-syntax-geometry-profiles for IfcProfileDef.IfcMaterialProfileSetUsage carries ForProfileSet, optional CardinalPoint
(IfcCardinalPointReference), and optional ReferenceExtent.
IfcCardinalPointReference is a defined type over INTEGER, NOT an enumeration :
TYPE IfcCardinalPointReference = INTEGER;
WHERE
GreaterThanZero : SELF > 0;
END_TYPE;
Index meaning : 1-9 bounding-box points (bottom / mid-depth / top, each
left / centre / right) ; 10-14 geometric centroid and aligned variants ;
15-19 shear-centre and aligned variants ; 20 lowest point inside a pipe or
channel profile. Other index values are outside the specification's scope.
Constituent materials : windows, doors, composite parts (IFC4+)
For composite elements that are neither layered nor profiled (a window : frame +
glazing + sealant). IfcMaterialConstituentSet and IfcMaterialConstituent were
introduced in IFC4 ; they replace IfcMaterialList for this purpose.
ENTITY IfcMaterialConstituentSet
SUBTYPE OF (IfcMaterialDefinition);
Name : OPTIONAL IfcLabel;
Description : OPTIONAL IfcText;
MaterialConstituents : OPTIONAL SET [1:?] OF IfcMaterialConstituent;
END_ENTITY;
ENTITY IfcMaterialConstituent
SUBTYPE OF (IfcMaterialDefinition);
Name : OPTIONAL IfcLabel;
Description : OPTIONAL IfcText;
Material : IfcMaterial;
Fraction : OPTIONAL IfcNormalisedRatioMeasure;
Category : OPTIONAL IfcLabel;
END_ENTITY;
IfcMaterialConstituent.Material is required ; Fraction is the fraction of total
volume or weight as an IfcNormalisedRatioMeasure ([0..1]).
IfcMaterialList : the IFC2x3 legacy mechanism
ENTITY IfcMaterialList;
Materials : LIST [1:?] OF IfcMaterial;
END_ENTITY;
IfcMaterialList is a bare ordered list of materials with no per-part semantics,
fractions, thicknesses, or geometry. It is the IFC2x3 composite mechanism. It is
retained in IFC4 only for round-tripping IFC2x3 data. ALWAYS use
IfcMaterialConstituentSet for a new IFC4+ composite. An IfcMaterialList in a new
IFC4 file is a smell : see references/anti-patterns.md.
IfcMaterialProperties
ENTITY IfcMaterialProperties
SUBTYPE OF (IfcExtendedProperties);
Material : IfcMaterialDefinition;
END_ENTITY;
Supertype chain : IfcPropertyAbstraction → IfcExtendedProperties →
IfcMaterialProperties. It inherits Name (OPTIONAL IfcIdentifier), Description
(OPTIONAL IfcText), and Properties (SET [1:?] OF IfcProperty).
IFC4 change : in IFC2x3 material properties used specialised abstract subtypes
(IfcMechanicalMaterialProperties, IfcThermalMaterialProperties,
IfcHygroscopicMaterialProperties, IfcGeneralMaterialProperties,
IfcOpticalMaterialProperties). IFC4 deleted all of those, made
IfcMaterialProperties a single non-abstract entity, and widened Material from
IfcMaterial to IfcMaterialDefinition so properties can attach to layers,
profiles, constituents, and their sets. NEVER write the deleted subtypes in IFC4+.
The set-on-type, usage-on-occurrence rule
For layered and profiled elements the model splits the material across two levels :
- The element type (
IfcWallType, IfcBeamType, ...) is associated with the
bare set (IfcMaterialLayerSet or IfcMaterialProfileSet).
- Each element occurrence (
IfcWall, IfcBeam, ...) is associated with a
usage (IfcMaterialLayerSetUsage / IfcMaterialProfileSetUsage) that points
back at the same set via ForLayerSet / ForProfileSet and adds placement.
ALWAYS put the usage on the occurrence and the bare set on the type. NEVER associate
an IfcMaterialLayerSetUsage or IfcMaterialProfileSetUsage with an element type :
the IFC specification restricts the usage entities to occurrences.
Version differences (compact)
| Item | IFC2x3 | IFC4 | IFC4.3 |
|---|
IfcMaterial.Description, .Category | absent | present | present |
IfcMaterialLayer.Name/.Description/.Category/.Priority | absent | present | present |
IfcMaterialLayer.LayerThickness type | IfcPositiveLengthMeasure | IfcNonNegativeLengthMeasure | IfcNonNegativeLengthMeasure |
IfcMaterialLayerSet.Description | absent | present | present |
Profiled family (IfcMaterialProfileSet etc.) | absent | present | present |
Constituent family (IfcMaterialConstituentSet etc.) | absent | present | present |
IfcMaterialProperties | abstract, typed subtypes | one non-abstract entity | one non-abstract entity |
IfcMaterialList | composite mechanism | legacy, retained | legacy, retained |
Decision Trees
Which material definition for a given element?
What is the element made of?
|
+-- One homogeneous substance (a solid concrete footing)
| --> IfcMaterial, associated directly.
|
+-- Parallel layers with thickness (wall, slab, roof, plate)
| --> IfcMaterialLayerSet on the type;
| IfcMaterialLayerSetUsage on each occurrence.
|
+-- A cross-section profile extruded along an axis (beam, column, pile) [IFC4+]
| --> IfcMaterialProfileSet on the type;
| IfcMaterialProfileSetUsage on each occurrence.
|
+-- Named composite parts, not layered, not profiled (window, door) [IFC4+]
| --> IfcMaterialConstituentSet with one IfcMaterialConstituent per part.
|
+-- A plain list of materials, IFC2x3 round-trip only
--> IfcMaterialList. NEVER author this fresh in IFC4+.
Set or usage : which goes where?
Are you associating a layer-set or profile-set?
|
+-- The target is an element TYPE (IfcWallType, IfcBeamType)
| --> associate the bare set (IfcMaterialLayerSet / IfcMaterialProfileSet).
|
+-- The target is an element OCCURRENCE (IfcWall, IfcBeam)
--> associate the usage (IfcMaterialLayerSetUsage / IfcMaterialProfileSetUsage),
whose ForLayerSet / ForProfileSet points back at the type's set.
Is this attribute mine to write?
About to write a value for IfcMaterialLayerSet.TotalThickness?
|
+-- ALWAYS stop : TotalThickness is DERIVED (IfcMlsTotalThickness).
The reader computes it from the layer thicknesses. NEVER serialize it.
Patterns
Pattern : Associate a plain material
ALWAYS create one IfcMaterial with a required Name, then bind it with one
IfcRelAssociatesMaterial whose RelatingMaterial is that IfcMaterial and whose
RelatedObjects lists the elements.
ALWAYS reuse one IfcRelAssociatesMaterial across every element that shares the
material : RelatedObjects is a set.
NEVER duplicate an identical IfcMaterial per element : create it once and reference
it.
Pattern : Build a layered wall or slab
ALWAYS model a layered element with IfcMaterialLayerSet holding an ordered
MaterialLayers list ; each IfcMaterialLayer carries a Material and a
LayerThickness.
ALWAYS associate the bare IfcMaterialLayerSet with the element type and an
IfcMaterialLayerSetUsage with each occurrence ; the usage's ForLayerSet
points at the same IfcMaterialLayerSet.
NEVER write a value for the derived TotalThickness.
NEVER attach the IfcMaterialLayerSetUsage to the type : usage is occurrence-only.
Pattern : Build a profiled beam or column (IFC4+)
ALWAYS model a profiled element with IfcMaterialProfileSet holding
MaterialProfiles ; each IfcMaterialProfile carries a required Profile
(IfcProfileDef) and an optional Material.
ALWAYS associate the bare IfcMaterialProfileSet with the element type and an
IfcMaterialProfileSetUsage with each occurrence ; set CardinalPoint to align the
profile to the member axis when needed.
NEVER use the profiled family in an IFC2x3 file : it does not exist before IFC4.
Pattern : Build a constituent set for a window or door (IFC4+)
ALWAYS model a non-layered, non-profiled composite with IfcMaterialConstituentSet ;
add one IfcMaterialConstituent per part (frame, glazing, sealant), each with a
required Material and an optional Name naming the part.
NEVER use IfcMaterialList for a new composite : IfcMaterialConstituentSet carries
the per-part names, fractions, and categories that IfcMaterialList cannot.
Pattern : Attach material properties
ALWAYS attach material properties with IfcMaterialProperties, whose Material
references the IfcMaterialDefinition (a material, layer, profile, or constituent)
and whose Properties set holds IfcProperty instances.
ALWAYS use the single non-abstract IfcMaterialProperties entity in IFC4 and IFC4.3.
NEVER write IfcMechanicalMaterialProperties, IfcThermalMaterialProperties,
IfcHygroscopicMaterialProperties, IfcGeneralMaterialProperties, or
IfcOpticalMaterialProperties in IFC4+ : those subtypes were deleted in IFC4.
Pattern : Honour the version differences
ALWAYS check the target schema before writing a material structure : the profiled
and constituent families and several attributes are IFC4 additions.
ALWAYS write only IfcMaterial.Name in IFC2x3 : Description and Category were
added in IFC4.
NEVER carry an IfcMaterialList into a freshly authored IFC4+ model : it is a legacy
artefact kept only for round-tripping IFC2x3 data.
Reference Links
references/methods.md : the complete verified entity definitions for the layered,
profiled, and constituent families side by side, IfcRelAssociatesMaterial,
IfcMaterial, IfcMaterialProperties, IfcMaterialList, the IfcMaterialSelect
and IfcMaterialDefinition trees, the IfcCardinalPointReference index table, and
the per-version difference matrix.references/examples.md : worked STEP scenarios : a plain material association, a
three-layer wall with type and occurrence, a steel beam profile set, a window
constituent set, material properties, and an IFC2x3 IfcMaterialList.references/anti-patterns.md : the failure modes this skill prevents, each with the
reason it fails.
Official sources
Related skills
ifc-syntax-geometry-profiles : IfcProfileDef, the cross-section that
IfcMaterialProfile.Profile requires.ifc-syntax-property-sets : IfcProperty and the property entities that
IfcMaterialProperties.Properties holds.ifc-impl-data-enrichment : the workflow for adding materials to an existing model.ifc-errors-property-set-mistakes : material and property failure modes in real
files.
