Add Material API implementation

[germa89]

Description of the feature

We should aim to have a comprehensive materials API in DPF.

At the moment there are many operators in place, but I believe they lack the "connection" between them in order to expose these feature properly.

As first step, let's talk about how the API should look like. Then we can decide how to couple the operators in order to obtain the desired API.

Steps for implementing the feature

Personally, I would propose the following pseudo-code for the API.

Proposed implementation

>>> from ansys.dpf import core as dpf
>>> import numpy as np

>>> model = dpf.Model('file.rst')

>>> mat1 = model.materials.get_material(1)
>>> mat1.name = "Structural Steel"
>>> mat1.id = "1"
>>> mat1.uud = "asdf-asdf-asdf-asdf" #whatever thing is named.
>>> mat1.units = "MKS"

>>> mat1.add_density(7900)
>>> mat1.add_isotropic_elasticity(ex=1E9, nu=0.3)

>>> mat1
Material 1: Structural Steel
uud: asdf-asdf-asdf-asdf
Properties
----------
Density: 7900 kg/m3
Isotropic Elasticity:
	EX = 1E9 N/m2
	NU = 0.3
>>> mat1.ex # we should be able to use MAPDL labels (EX, NUXY, KXX, etc) to get the info.
1E9
>>> mat1['EX']
1E9

>>> mat1.dens = 8000
>>> mat1.dens
8000

>>> from ansys.dpf import units, custom_unit
>>> my_custom_units = custom_unit(lenght=units.lenght.mm,
temperature=units.temperature.C) # rest default to MKS.
>>> from ansys.dpf.core import Physics
>>> mat1.add_isotropic_resistivity(
	values = np.array([1, 2, 3, 4])*1E-9,
	reference = Physics.temperature,
	reference_values = [10, 20, 30, 40],
	units = my_custom_units
	)
>>> mat1.kxx
Isotropic Resistivity
Temperature dependent
Values Temperature
1E-9	10
2E-9	20
3E-9	30
4E-9	40
>>> mat1.kxx.units
Lenght: mm
Temperature: C
Mass: Kilograms
Time: Seconds
...
>>> mat1.kxx.units(lenght=units.lenght.m)
>>> mat1.kxx.units
Lenght: m
Temperature: C
Mass: Kilograms
Time: Seconds

I believe this API is pythonic enough but also rigorous enough to allow a clear material definition.

Personally, it is the kind of thing I would like to see in PyMAPDL.

Please, feel free to propose modification.

I'm happy to discuss this.

Useful links and references

No response

[germa89]

Pinging @PProfizi for updates and improvements.

Pinging @cbellot000 @ayush-kumar-423 @janvonrickenbach @rlagha

Pinging @akaszynski @koubaa @da1910 because they probably are interested (maybe)

[PProfizi]

@germa89 In your pseudo-code you propose a lot of setters, yet I am not sure if this is something we should make available (at least at first) as to me that would entail actually changing the values stored at the server level, maybe even in the material files? What would be the expected outcome of those setters? This seems like pre-treatment to me and I do not see it being coherent with what PyDPF proposes now, but I may definitely be biased.

[germa89]

In your pseudo-code you propose a lot of setters,

You are right.

that would entail actually changing the values stored at the server level

I am not sure about this.

maybe even in the material files

I do not think that would be an issue, you should not change the files until you save the model.

What would be the expected outcome of those setters?

What do you mean? What should they return? I would say None.

I do not see it being coherent with what PyDPF proposes now, but I may definitely be biased

It should be noticed that I am not familiar at all with PyDPF. I only use PyMAPDL, but I find this proposal (as well as PyMAPDL post processing module) aligned with the sort of API you would expect in packages as matplotlib and numpy; and I think that is an advantage. In fact, this proposal is also aligned with PyDPF-Post (but let's not bring that in here yet).

Anyway, this is just a first draft, I would suggest you to edit/delete/improve it as much as you want :)

[da1910]

A couple of initial questions, I'm not very familiar with how DPF interacts with MAPDL, but from a Materials perspective some things occur to me.

1. How would this fit in with the existing MAPDL commands to manage materials? Does your snippet above run before the MAPDL solver or after?
2. Are all the material models supported in DPF? If so there are a lot of nonlinear models we would need to support, ideally this would be done somewhere in a common package, rather than in each bit of pyansys separately.
3. How would this interact with MAPDL material cards, either in MatML format or the legacy APDL format?

[da1910]

More API related comments or questions:

• How high or low-level is this aimed? I'd strongly prefer human readable names for properties as the default, so Material.density rather than Material.dens, we have enough RAM for more than 4 letters these days. Either we can provide aliases for the MAPDL codes or use the __getitem__() to resolve them.
• We should be careful about unit_system vs unit
• Is there value in making things like id and uuid editable? They're used for traceability in a lot of places, I'm not sure it makes sense?

[akaszynski]

Is there value in making things like id and uuid editable?

Nope.

This is all related to a wider topic of creating a materials database/library that has absolutely not materialized as of yet. Some communication should be made about that to certain developers. @chadqueen, I know that you had visibility into this failed effort, but if the code is there, we might have something we could reuse or at least know what not to do.

[chadqueen]

I think it is ideal to replace unique material implementations per component/product with a standard library and interfaces. I feel the materials business unit / Granta has the expertise here that we should rely upon, where identifiers can have context, material parameters have accurate names/units/validation and material databases are maintained. We should promote a Granta material library effort for all layers of the stack (python client library, protobuf definitions, C# nuget, C++ package, etc).

Within the material calibration project specifically, grpc definitions had all the units, quantity, parameter items abstracted, but a centralized library really would have helped. In the end each side of that contract really had separate unit system expectations and lots of assumptions had to be made to "make it work". I can review it with anyone interested.

[koubaa]

brain dump:

• I need a python material library to define materials for mapdl for something I'm working on. Because of where its deployed it cannot depend on any running instances of ansys products (sorry can't disclose more info on public github about this - but ping me if you want to know more)
• DPF doesn't seem like the right place for this
• I support adding a new mapdl command to read materials from some agreed upon file format. I do not mean pymapdl, I really mean mapdl.
• The Ansys code which converts generic material models into mapdl commands is sort of locked into mechanical, it would be nice to pull that out as a separate component
• Material models are somewhat physics specific, so consistency in terms of API design for fluids/emag/structural is a good idea but using the same library across all physics seems like an overreach and could cause more problems than it solves.

[chadqueen]

There are a dozen+ material parameters that are additive specific and multiple characterized/calibrated lookup files for thermal characteristics/etc. There is essentially significant validation required to confirm a material is sufficiently defined for additive related simulations. Putting all those requirements in separate projects with unique implementations has been a nightmare. If there was one shared methodology for such things the overreach can also be a savior in consistency and speed of implementation.

[janvonrickenbach]

I think we should clarify the goal of the Material API in dpf. For my perspective (as a dpf plugin developer for composite simulations), dpf needs to provide mechanism to access material properties that were used in the simulation. There is no need to define material properties. The biggest challenge here are variable material properties, which are not readily available in the rst file. We have already implemented a Framework/API for variable material properties in the C++ backend of dpf. I think the first goal should be to make this API available from python.

[mcMunich]

For a customer I once we started a ACT method to extract all material properties in the model.
As pointed out, it is not simple due to the various formats of the data (tables, parameters, etc) but there must be some not too difficult method to recursively iterate through the data and make a dictionary with material properties. Of course this was in Mechanical ACT where the materials are accessible, not sure how that could be done in pydpf.
What I require for a project is the S-N data (cycles to failure). That would be useful for fatigue analyses.