Material

Overview
This page is about the Material data system in FreeCAD.

It is currently being edited to reflect changes to the Material system currently under development.

Abstract
In a departure from how it was implemented in previous versions, materials are no longer implemented as a simple dictionary. The previous system had the advantage of simplicity with the disadvantage of a limited range when describing material properties.

In the new system properties are defined separately as a series of YAML files. Properties are then combined into a property description with values specified for the required properties. Newer data types, such as arrays, mean that this can no longer be accessed using simple dictionaries. Rather an API is used to access the material property and data values. This allows for greater capabilities than was previously possible.

Rules
Every property set has only one mandatory entry which is "Name". This is the primary key of the material. The rest of the material properties are optional or can be retrieved out of a material DB.

Property names (key) are ordered by strings separated by underscores. The first substring is named by the application or standard, the following can be used to further group the properties. The Values can also be grouped by underscores, e.g. to separate different sorts of steel. Examples:
 * Name=Steel_Cast
 * SpecificWeight=7.85 (at 20° in kg/mm3)
 * EN10027_name = S235JR+AR (steel standard EN 10027-1)
 * FEM_YoungsModulus = xx (in  mm−1·kg·s−2)
 * FEM_YoungsModulus_Z
 * FEM_YoungsModulus_X

Each property has a human readable description on this Material page, with links to further information (e.g. Wikipedia).

For each property a unit has to be defined, based on the FreeCAD internal unit mm-kg-s! That allows consistent usage and translation.

The key (name) and the value of the property uses only ASCII characters (7-bit). The keys are written in Camel-Case but interpreted case-insensitive.

The underscores allow later a tree view property editor/viewer which allow folding.

Tools
There are some good resources out there handle materials more easy:
 * Units calculator to get your material information in the Unit needed for FreeCAD
 * http://www.matweb.com/ free of charge Material database with thousands of material values
 * UUID generator to create unique UUIDs for new models. A Version 4 UUID is recommended.

Properties
In contrast with the previous materials standard, material properties are clearly defined. They have been designed to be granular and extensible. Properties can inherit multiple properties adding only what is different. This will improve searching and simplify implementation.

Currently there is no dedicated property editor. It can be edited using any YAML tool, or a simple editor such as nano or notepad.

The property definition files are referred to as models.

Example Property Model YAML file
Rather than a large monolithic definition file, properties are granular, typically focused on a specific task. Models fall into two basic categories:
 * Physical models: identified by the keyword 'Model' as shown here, these define physical properties of the material
 * Appearance models: identified by the keyword 'AppearanceModel', these define how the material will be displayed.

Each model has a unique identifier, or UUID, that is used to reference it internally. Consistency of this UUID is important as changing it for one document can also affect other documents. As a general rule, additions to the definition don't require an identifier change, as they can still be used in other documents, but value changes would require a new UUID.

An optional URL can link to a detailed description of the material property being described. Given that this is a description of the property and not the material itself it should be pretty generic at this point. A shorter description, typically one or two lines, can be included in the model description as well.

Each material can also include a DOI (Digital Object Identifier) that links through https://www.doi.org/ to a research publication or similar item of interest.

Inheritance
Inheritance is a new capability. There are two principal use cases.

One use case is to provide the ability to tweak models without breaking other documents. For example, in cases where a property type is different, you can define a derived property model that only changes that specific property without breaking any existing documents that reference it.

A second use case is to group properties in a searchable fashion. For example, all physical objects have density, and in many cases that will be all the information available for that material. In cases where linear elasticity properties are available, we would want to include those as well. In yet another example where the elasticity is different in different directions, such as wood, we can define yet another model that is derived from density. Information is not duplicated across the 3 property models. Additionally, we can do a search for materials that have the density property and return all three models.

The example shown above inherits from two other property definitions. It does this by specifying the 'Inherits' keyword followed by a list of the model names and identifiers. If there is no inheritance this section may be omitted.

Properties
Properties are defined by providing the name of the property followed by a series of descriptors. The 'Type' descriptor is always required. The remaining descriptors are only required if required to complete the Type information. The URL and description are optional but recommended where possible.

Lists
There are three list types: 'List', 'FileList', and 'ImageList'. In reality all three are the same except that they use different editors. For the 'FileList', each entry has a file chooser. Similarly the 'ImageList' opens the image editor. 'ImageList' is different in that it is a very large string representation of an image and may produce extremely large material card files. Use with caution.

2D Arrays
Arrays have some unique properties compared to other property types. Each of the array columns need to be described necessitating the addition of the 'Columns' property. The columns property is then a list of properties describing each column.

2D arrays have a minimum of 2 columns, and only support the 'Quantity' property type. This may be expanded to other property types in future.

Values in the array are specified by providing a value from the first column.

3D Arrays
3D arrays are similar in implementation to 2D arrays described in the previous sections. There is a 'Columns' keyword followed by a list of properties to describe the columns. The first column describes the depth or 3rd dimension of the array, with the remaining columns describing the remaining columns. This can be thought of as an indexed list of 2 dimensional arrays.

Since a 2 dimensional array requires a minimum of 2 dimensions, this will require a minimum of 3 columns.

Values in the array are accessed by first specifying the depth, then the value from the first column of the 2D array (the second column here).

A note about arrays
These are a new feature not previously available. Many capabilities may be added in the future that aren't currently implemented. For example, arrays with columns of strings are potentially useful but not currently implemented.

Interpolation is an important feature that isn't currently implemented. For example, an array with row entry values of 1 and 2 will only return exact matches. So a lookup of 1.5 will return an error. In future, the arrays will determine an approximate value by interpolating from available data.

Material Database
Given that above standard is implemented, it would be stupid to store all the properties again and again to objects. Basically we can build up a Material DB with the Name as a primary key. So if you have no special needs for your material, you just define e.g. Name=Steel and FreeCAD can retrieve all properties from that DB. Every additional property you set in the map overrides the one from the DB.

In the future we can host that DB somwhere in the Web and build up a general OpenSource material DB.

At the moment I think of a compiled in mini dataset with a set of "basic" materials and its basic properties and a SQLite based full version.

Material.py
Since handling material-properties is a tedious work we should implement a Python front-end module called [source]. This will be the place to implement all kind of helper methods for material handling.
 * Calculation of Mass out of Volume and Density
 * Translation in different unit systems
 * Calculation needed in special application (e.g. FEM)
 * and anything else we don't know yet

The module should be implemented that way it can run in FreeCAD or stand alone on the command line (material-property-map has be given as python map).

The FreeCAD material card file format
Working with materials means often import/export material-definitions. Therefore a file format is needed. Since we have only key/value form, we can use a simple and easy to read and parse file format. Therefore the ini-file format is chosen. Its standardized and there are already parser available. E.g the Config parser module in python.

Each material definition resides in a file with the ending. Some of these files are part of the FreeCAD source and get compiled into the binary. This is to save overhead in distribution and access. But also files can be placed and searched on different places to allow additional non-standard material definitions.

Material properties
Here now the description of agreed material-properties. Feel free to add a subsection for the material-properties of you field of expertise.

General
ToDos: add some properties with an ordering system for materials (metal, alloy, mineral, wood, ....)

Mechanical
ToDos: further add properties needed for mechanical design.

Graphical
This section defines material-properties which are related to the visual appearance of the material. The

TODO

 * add sustainability & LEED properties