Tutorial - nogula/elematic GitHub Wiki
The tutorial herein uses an example MatML file, found in elematic\res\example_matml\INCONEL 718 - ASTM F3055 CLASS D.xml. Download this file to a convenient location, or use your own supplied data.
The Python api (elematic.api.MatML_api) is more or less a one-to-one conversion of the MatML XML schema to a Python classes data structure, originally generated programmatically by the generateDS program. The MatML schema was developed by NIST with on of the goals to standardize the exchange of materials information.
Tip
It is greatly recommended to familiarize yourself with the MatML schema prior to using this package. For the most part, the data structure within elematic mirrors that of the MatML schema, and therefore having familiarity with MatML will improve the usefulness you get out of elematic.
One method to gain familiarity with MatML is simply to inspect how example files, some of which are available here.
The following code snippets will utilize these import statements:
>>> import elematic.api
MatML data can be imported to elematic via two primary means: from a file, or from a string. For this tutorial, only the from-file method will be covered. To import a .xml file, use the import_xml() function:
>>> input_file = r"INCONEL 718 - ASTM F3055 CLASS D.xml"
>>> library = elematic.api.import_xml(input_file)
The import_xml() function returns a MatML_Doc instance which represents the root element of the XML data. For instance,
>>> print(library)
<MatML_Doc>
<Material id="ID1001">
<BulkDetails>
<Name>INCONEL 718 PER ASTM F3055 CLASS D</Name>
<Class>
<Name>METAL</Name>
</Class>
<Subclass>
<Name>NICKEL ALLOY</Name>
</Subclass>
...
[and so on -- snipped for brevity]
where,
>>> print(type(library))
<class 'elematic.api.MatML_api.MatML_Doc'>
MatML files may contain many material entries within them, so it is helpful to determine what material cards are available within the library. To do so, we access the Material attribute of the MatML_Doc instance:
>>> for material in library.Material:
... print(material.BulkDetails.Name.valueOf_)
...
INCONEL 718 PER ASTM F3055 CLASS D
It happens for this particular file that only one material is available.
Tip
As a rule, accessing attributes of any of the MatML schema elements which have maxOccurs="unbounded" (e.g., there is no bound on the number of material elements in a MatML_Doc element) will always return a list. For instance:
>>> print(library.Material)
[<elematic.api.MatML_api.Material object at 0x0000024823AF0E90>]
If an element may occur up to one time, then accessing that attribute will always return the instance itself. For instance:
>>> print(type(library.Material[0].BulkDetails))
<class 'elematic.api.MatML_api.BulkDetails'>
Notice how the BulkDetails was accessed by indexing Material at [0]. Omitting this would raise an AttributeError since a list has no attribute for BulkDetails. Only one BulkDetails element may exist per Material.
For convenience, the utilities are provided by elematic to report information on a given material by using the elematic.api.report() function. Passing a material entry as the argument:
output of report function
>>> elematic.api.report(library.Material[0])
Material ID: ID1001
Bulk Details
‾‾‾‾‾‾‾‾‾‾‾‾
Name: INCONEL 718 PER ASTM F3055 CLASS D
Class: METAL
Subclass: NICKEL ALLOY
Processing: STRESS RELIEF
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 1950
│ ├── Units: °F
├── Parameter: DURATION ( pa_2 )
│ ├── Data: 90
│ ├── Units: min
Processing: HOT ISOSTATIC PRESSING
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 2125
│ ├── Units: °F
├── Parameter: DURATION ( pa_2 )
│ ├── Data: 200
│ ├── Units: min
├── Parameter: PRESSURE ( pa_3 )
│ ├── Data: 14750
│ ├── Units: lbf / in^2
Processing: SOLUTION TREATMENT
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 1750
│ ├── Units: °F
├── Parameter: DURATION ( pa_2 )
│ ├── Data: 60
│ ├── Units: min
Processing: QUENCH
├── Air or argon rapid cooling
Processing: ARTIFICIAL AGEING 1
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 1325
│ ├── Units: °F
├── Parameter: DURATION ( pa_2 )
│ ├── Data: 480
│ ├── Units: min
Processing: ARTIFICIAL AGEING 2
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 1150
│ ├── Units: °F
├── Parameter: DURATION ( pa_2 )
│ ├── Data: 600
│ ├── Units: min
Processing: QUENCH
├── Air or argon rapid cooling
Property data: TENSILE ULTIMATE STRENGTH ( pr_1 )
├── Data: 192000,153000
├── Units: lbf / in^2
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 70,1200
│ ├── Units: °F
Property data: TENSILE YIELD STRENGTH ( pr_2 )
├── Data: 159000,128000
├── Units: lbf / in^2
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 70,1200
│ ├── Units: °F
Property data: ELONGATION ( pr_3 )
├── Data: 17.83,20.0
├── Units: %
├── Parameter: TEMPERATURE ( pa_1 )
│ ├── Data: 70,1200
│ ├── Units: °F
Property data: MODULUS OF ELASTICITY ( pr_4 )
├── Data: 26500000,29000000
├── Units: lbf / in^2
This displays the available materials information associated with that card, along with identifier information for accessing those data. For instance, we see that the material has property data for tensile yield strength at 70 and 1200 °F. The tensile data is in the pr_2 property with temperature in the pa_1 parameter.
To utilize the property and parameter data in other Python expressions, the data must be accessed by the material's PropertyData elements within the BulkDetails. Based on the material report obtained above, say the tensile yield strength is of interest.
The elematic API provides means to translate material information from one form to MatML. Currently, the only importer available is for ANSYS GRANTA's catalog of Metallic Materials Properties Development and Standardization (MMPDS) Handbook, available from NASA's Materials and Processes Technical Information System (MAPTIS). Additional importers are planned.
Note
The importer has been verified with GRANTA software version 22.2.860.0.
To use the importer:
- Download the record of interest as an Excel workbook.
- In Python, use the expression:
>>> material_card = elematic.api.import_granta_maptis_mmpds(input_file_path)
The importer will return a MatML_Doc instance with the translated materials information. Records which do not have dependent data take only a few seconds to import. Records with dependent data can take upwards of a few minutes.
A note on exporting data from ANSYS GRANTA...
In theory, GRANTA enables exporting materials information as a MatML file. However, not all data are exportable (particularly temperature-dependent properties), despite what the report function claims. Therefore, an importer from the Excel version of the exported record was created, since the Excel template contains all available data for the record.Currently, data may only be exported to an XML file. Exporters to other file formats are planned. Exporting MatML data to an XML file is straightforward; simply use the export() method of any object (e.g., the MatML_Doc). For instance, say library is a MatML_Doc object:
>>> library.export(output_filename, level=0)
Doing so will write the contents of the object to an XML file.
Pretty print is also available to print the instance represented as XML data to the stdout.