Package: matadi
Material Definition with Automatic Differentiation.matADi is a 3.8+ Python package for the definition of a constitutive hyperelastic material formulation by a strain energy density function. Bothgradient(stress) andhessian(elasticity tensor) are carried out byAutomatic Differentiation (AD)usingcasADi[1] as a backend. A high-level interface for hyperelastic materials based on the deformation gradient exists. Several isotropic hyperelastic material formulations like the Neo-Hookean or the Ogden model are included in the model library. Gradient and hessian methods allow input data with trailing axes which is especially useful for Python-based finite element modules, e.g.scikit-femorFElupe. Mixed-field formulations suitable for nearly-incompressible material behavior are supported as well as single-field formulations based on the deformation gradient. A numerical lab is included to run, plot and analyze homogeneous uniaxial, equi-biaxial, planar shear and simple shear load cases.InstallationInstallmatADifrom PyPI via pip.pipinstallmatadiUsageFirst, a symbolic variable on which our strain energy function will be based on has to be created.Note:A variable of matADi is an instance of a symbolic variable of casADi (casadi.SX.sym). Most (but not all) ofmatadi.mathfunctions are simple links to (symbolic) casADi-functions.frommatadiimportVariable,Materialfrommatadi.mathimportdet,transpose,traceF=Variable("F",3,3)Next, take your favorite paper on hyperelasticity or be creative and define your own strain energy density function as a function of some variablesx(wherexis always alistof variables).defneohooke(x,C10=0.5,bulk=200.0):"""Strain energy density function of a nearly-incompressibleNeo-Hookean isotropic hyperelastic material formulation."""F=x[0]J=det(F)C=transpose(F)@FreturnC10*(J**(-2/3)*trace(C)-3)+bulk*(J-1)**2/2With this simple Python function at hand, we create an instance of aMaterial, which allows extraargsandkwargsto be passed to our strain energy function. This instance now enables the evaluation of bothgradient(stress) andhessian(elasticity) via methods based on automatic differentiation - optionally also on input data containing trailing axes. If necessary, the strain energy density function itself will be evaluated on input data with optional trailing axes by thefunctionmethod.Mat=Material(x=[F],fun=neohooke,kwargs={"C10":0.5,"bulk":10.0},)# init some random deformation gradientsimportnumpyasnpdefgrad=np.random.rand(3,3,5,100)-0.5forainrange(3):defgrad[a,a]+=1.0W=Mat.function([defgrad])[0]P=Mat.gradient([defgrad])[0]A=Mat.hessian([defgrad])[0]In a similar way, gradient-vector-products and hessian-vector-products are accessible viagradient_vector_productandhessian_vector_productmethods, respectively.v=np.random.rand(3,3,5,100)-0.5u=np.random.rand(3,3,5,100)-0.5W=Mat.function([defgrad])[0]dW=Mat.gradient_vector_product([defgrad],[v])[0]DdW=Mat.hessian_vector_product([defgrad],[v],[u])[0]Template classes for hyperelasticitymatADi provides several template classes suitable for hyperelastic materials. Some isotropic hyperelastic material formulations are located inmatadi.models(see list below). These strain energy functions have to be passed as thefunargument into an instance ofMaterialHyperelastic. Usage is exactly the same as described above. To convert a hyperelastic material based on the deformation gradient into a mixed three-field formulation suitable for nearly-incompressible behavior (displacements,pressureandvolume ratio) an instance of aMaterialHyperelasticclass has to be passed toThreeFieldVariation. Forplane strainorplane stressuseMaterialHyperelasticPlaneStrain,MaterialHyperelasticPlaneStressIncompressibleorMaterialHyperelasticPlaneStressLinearElasticinstead ofMaterialHyperelastic. For plane straindisplacements,pressureandvolume ratiomixed-field formulations useThreeFieldVariationPlaneStrain. For a two-field formulation (displacements,pressure) useTwoFieldVariationon top ofMaterialHyperelastic.frommatadiimportMaterialHyperelastic,ThreeFieldVariationfrommatadi.modelsimportneo_hooke# init some random datapressure=np.random.rand(5,100)volratio=np.random.rand(5,100)/10+1kwargs={"C10":0.5,"bulk":20.0}NH=MaterialHyperelastic(fun=neo_hooke,**kwargs)W=NH.function([defgrad])[0]P=NH.gradient([defgrad])[0]A=NH.hessian([defgrad])[0]NH_upJ=ThreeFieldVariation(NH)W_upJ=NH_upJ.function([defgrad,pressure,volratio])P_upJ=NH_upJ.gradient([defgrad,pressure,volratio])A_upJ=NH_upJ.hessian([defgrad,pressure,volratio])The output ofNH_upJ.gradient([defgrad, pressure, volratio])is a list with gradients of the functional as[dWdF, dWdp, dWdJ]. Hessian entries are provided as a list of upper triangle entries, e.g.NH_upJ.hessian([defgrad, pressure, volratio])returns[d2WdFdF, d2WdFdp, d2WdFdJ, d2Wdpdp, d2WdpdJ, d2WdJdJ].Availableisotropic hyperelastic material models:Linear Elastic(code)Saint Venant Kirchhoff(code)Neo-Hooke(code)Mooney-Rivlin(code)Yeoh(code)Third-Order-Deformation (James-Green-Simpson)(code)Ogden(code)Arruda-Boyce(code)Extended-Tube(code)Van-der-Waals (Kilian)(code)Availableanisotropic hyperelastic material models:Fiber (code)Fiber-family (+/- combination of single Fiber) (code)Holzapfel Gasser Ogden(code)Availablemicro-sphere hyperelastic frameworks(Miehe, Göktepe, Lulei) [2]:affine stretch(code)affine tube(code)non-affine stretch(code)non-affine tube(code)Availablemicro-sphere hyperelastic material models(Miehe, Göktepe, Lulei) [2]:Miehe Göktepe Lulei(code)Any user-defined isotropic hyperelastic strain energy density function may be passed as thefunargument ofMaterialHyperelasticby using the following template:deffun(F,**kwargs):# user codereturnWIn order to apply the above material model only on the isochoric part of the deformation gradient [3], use the decorator@isochoric_volumetric_split. If the keywordbulkis passed, an additionalvolumetric strain energy functionis added to the base material formulation.frommatadi.modelsimportisochoric_volumetric_splitfrommatadi.mathimporttrace,transpose@isochoric_volumetric_splitdefnh(F,C10=0.5):# user code of strain energy function, e.g. neo-hookereturnC10*(trace(transpose(F)@F)-3)NH=MaterialHyperelastic(nh,C10=0.5,bulk=200.0)LabIn matADi'sLab:lab_coat: numeric experiments on homogeneous loadcases on compressible or nearly-incompressible material formulations are performed. For incompressible materials useLabIncompressibleinstead. Let's take the non-affine micro-sphere material model suitable for rubber elasticity with parameters from [2, Fig. 19] and rununiaxial,biaxialandplanar sheartests.frommatadiimportLab,MaterialHyperelasticfrommatadi.modelsimportmiehe_goektepe_luleimat=MaterialHyperelastic(miehe_goektepe_lulei,mu=0.1475,N=3.273,p=9.31,U=9.94,q=0.567,bulk=5000.0,)lab=Lab(mat)data=lab.run(ux=True,bx=True,ps=True,shear=True,stretch_min=1.0,stretch_max=2.0,shear_max=1.0,)fig,ax=lab.plot(data,stability=True)fig2,ax2=lab.plot_shear(data)Unstable states of deformation can be indicated as dashed lines with the stability argumentlab.plot(data, stability=True). This checks whether if
a) the volume ratio is greater zero,
b) the monotonic increasing slope of force per undeformed area vs. stretch and
c) the sign of the resulting stretch from a small superposed force in one direction.Hints and usage in FEM modulesFor tensor-valued material definitions useMaterialTensor(e.g. any stress-strain relation). Also, please have a look atcasADi's documentation. It is very powerful but unfortunately does not support all the Python stuff you would expect. For example Python's default if-else-statements can't be used in combination with symbolic conditions (usemath.if_else(cond, if_true, if_false)instead). Contrary tocasADi, the gradient of the eigenvalue function is stabilized by a perturbation of the diagonal components.AMaterialwith state variablesA generalized material model with optional state variables, optionally for the (u/p)-formulation, is created by an instance ofMaterialTensor. If the argumenttriuis set toTruethe gradient method returns only the upper triangle entries of the gradient components. If some of the input variables are internal state variables the number of these variables have to be passed to the optional argumentstatevars. While the hyperelastic material classes are defined by a strain energy function, this one is defined by the first Piola-Kirchhoff stress tensor. Internally, state variables are equal to default variables but they are excluded from gradient calculations. State variables may also be used as placeholders for additional quantities, e.g. the initial deformation gradient at the beginning of an increment or the time increment. Hence, it is a very flexible class not restricted to hyperelasticity. For consistency, the methodsgradientandhessianof a tensor-based material refer to the gradient and hessian of the strain energy function.Includedpseudo-elastic material models:Ogden-Roxburgh(code)Includedviscoelastic material models:Finite-Strain-Viscoelastic(code)Includedother material models:MORPH(code)importnumpyasnpfrommatadi.modelsimport(displacement_pressure_split,neo_hooke,volumetric,ogden_roxburgh)frommatadiimportMaterialTensor,Variablefrommatadi.mathimportdet,gradientF=Variable("F",3,3)z=Variable("z",1,1)@displacement_pressure_splitdeffun(x,C10=0.5,bulk=5000,r=3,m=1,beta=0):"Strain energy function: Neo-Hooke & Ogden-Roxburgh."# split `x` into the deformation gradient and the state variableF,Wmaxn=x[0],x[-1]# isochoric and volumetric parts of the hyperelastic# strain energy functionW=neo_hooke(F,C10)U=volumetric(det(F),bulk)# pseudo-elastic softening functioneta,Wmax=ogden_roxburgh(W,Wmaxn,r,m,beta)# first Piola-Kirchhoff stress and updated state variable# for a pseudo-elastic material formulationreturneta*gradient(W,F)+gradient(U,F),Wmax# get pressure variable from augmented functionp=fun.p# Material as a function of `F` and `p`# with **one** additional state variable `z`NH=MaterialTensor(x=[F,p,z],fun=fun,triu=True,statevars=1)defgrad=np.random.rand(3,3,5,100)-0.5pressure=np.random.rand(1,5,100)statevars=np.random.rand(1,1,5,100)forainrange(3):defgrad[a,a]+=1.0dWdF,dWdp,statevars_new=NH.gradient([defgrad,pressure,statevars])d2WdFdF,d2WdFdp,d2Wdpdp=NH.hessian([defgrad,pressure,statevars])The Neo-Hooke, the MORPH and the Finite-Strain-Viscoelastic [4] material model formulations are available as ready-to-go materials inmatadi.modelsas:NeoHookeOgdenRoxburgh(),Morph()andViscoelastic().Hint:The state variable concept is also implemented for theMaterialclass.Simple examples for usingmatadiwithscikit-femas well as withfelupeare shown in the Discussion section.References[1] J. A. E. Andersson, J. Gillis, G. Horn, J. B. Rawlings, and M. Diehl,CasADi - A software framework for nonlinear optimization and optimal control, Math. Prog. Comp., vol. 11, no. 1, pp. 1–36, 2019,[2] C. Miehe, S. Göktepe and F. Lulei,A micro-macro approach to rubber-like materials. Part I: the non-affine micro-sphere model of rubber elasticity, Journal of the Mechanics and Physics of Solids, vol. 52, no. 11. Elsevier BV, pp. 2617–2660, Nov. 2004.[3] J. C. Simo, R. L. Taylor, and K. S. Pister,Variational and projection methods for the volume constraint in finite deformation elasto-plasticity, Computer Methods in Applied Mechanics and Engineering, vol. 51, no. 1–3, pp. 177–208, Sep. 1985,[4] A. V. Shutov, R. Landgraf, and J. Ihlemann,An explicit solution for implicit time stepping in multiplicative finite strain viscoelasticity, Computer Methods in Applied Mechanics and Engineering, vol. 265. Elsevier BV, pp. 213–225, Oct. 2013,