PCL and Customization > Modifying the Database Using PCL > Adding the New Material Properties
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">   
Adding the New Material Properties
The steps taken to define material properties are:
• Define the material categories (e.g., Isotropic, 2D Orthotropic, Composite) applicable to the analysis code.
• Define the material models (e.g., Elastic, Plastic, Creep) applicable to each material category.
• Define the material options (e.g., stress/strain curve versus hardening slope for plasticity) and the material option categories (e.g., Yield Function, Hardening Rule, Failure Theory) and then associate them with the material models.
• Define the generic material property words (e.g., Poisson Ratio 12), assign analysis code specific attributes to the material words.
• Group the material words into material records.
Material Categories
First, identify which material categories are valid for the new analysis code. Material categories are generally synonymous with material directionalities such as Isotropic and 2D Orthotropic. There are two steps in the process of defining material categories: defining the material categories and then associating these material categories to the analysis code.
Composite is also a material category. But, unlike the standard material categories Composite is automatically associated to all analysis codes. Composite is not user definable and should not be referenced in any of the material property definition commands described in this chapter.
The PCL function to define the material categories is:
:
db_create_matl_category
(<analy_code_id>, <cat_id>, <cat_name>, <dir_code>)
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<cat_id>
The ID to be used for referencing this material category. This ID must be unique with respect to all material category IDs previously defined in this analysis code but can and should be duplicates of material category IDs used in other analysis codes.
CHARACTER STRING
<cat_name>
The analysis code specific name of this material category.
INTEGER
<dir_code>
A code specifying the directionality of this material category. Material directionality codes are described in Material Directionalities, 472.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Unlike most of the element property data, material categories must be uniquely defined for a specific analysis code. But, for the sake of data transfer the material category IDs used should remain the same. For example, it would take two definition (“db_create_matl_category”) calls to define a given material category in both MSC Nastran and MSC.Marc, but the same material category ID would be used in both calls. The IDs which should be used for specific material categories are given below. If the material category of interest does not exist in the following list, a new and unique ID should be used.
 
<cat_name>
<cat_id>
Isotropic
1
3D Orthotropic
2
3D Anisotropic
3
2D Orthotropic
5
2D Anisotropic
4
To associate the material categories with the analysis code, the following PCL function should be used. 
 
db_create_valid_mtl_categories
(<analy_code_id>, <analy_type_id>, <cat_ids>, <num_cats>)
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<analy_type_id>
The ID of the analysis type. Analysis type IDs are described in Adding A New Analysis Preference (p. 357).
INTEGER ARRAY
<cat_ids>
The <num_cats> IDs of all the material categories valid for this analysis code.
INTEGER
<num_cats>
The number of material categories valid for this analysis code not including Composite which is automatically associated with all analysis codes.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Material Models
Next, define the material models used in the new analysis code and associate these material models with the appropriate material categories. In many cases, the material model is synonymous with the material linearity (e.g., elastic or plastic).
The PCL function to define the material models is: 
 
db_create_constitutive_model
(<analy_code_id>, <model_id>, <model_name>, <lin_code>)
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<model_id>
The ID to be used for referencing this material model. This ID must be unique with respect to all material model IDs previously defined in this analysis code but can and should be duplicates of material model IDs used in other analysis codes.
CHARACTER STRING
<model_name>
The analysis code specific name of this material model.
INTEGER
<lin_code>
A code specifying the linearity of this material model. Material linearity codes are described in Material Linearities, 472.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Unlike most of the element property data, material models must be uniquely defined for a specific analysis code. But, for the sake of data transfer the material model IDs used should remain the same. For example, it would take two definition (“db_create_constitutive_model”) calls to define a given material model in both MSC Nastran and MSC.Marc, but the same material model ID would be used in both calls. The IDs which should be used for specific material models are given below. If the material model of interest does not exist in the following list, a new and unique ID should be used.
 
<model_name>
<model_id>
Linear Elastic
1
Nonlinear Elastic
2
Elastoplastic
3
Failure
4
Creep
5
Viscoelastic
7
Swelling
8
Thermal
10
Hyperelastic
11
To associate the material models with the appropriate material categories, the following PCL function is used.
 
db_create_valid_const_models
(<analy_code_id>, <analy_type_id>, <cat_id>, <model_ids>, <num_models>)
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<analy_type_id>
The ID of the analysis type. Analysis type IDs are described in Adding A New Analysis Preference (p. 357).
INTEGER
<cat_id>
The material category ID as described in Material Categories, 529.
INTEGER ARRAY
<model_ids>
The <num_models> IDs of all the material models associated with this material category.
INTEGER
<num_models>
The number of material models valid for this material category.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Material Options and Material Option Categories
Now that the material models and material categories have been defined, create the material options and material option categories. Associate the right material options with each material option category and associate the appropriate material option categories with each of the material categories and material models.
The following function is used to define the material option categories. 
 
db_create_mtl_magics_defn
(<analy_code_id>, <analy_type_id>, <opt_cat_id>, <opt_cat_name>)
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<analy_type_id>
The ID of the analysis type. Analysis type IDs are described in Adding A New Analysis Preference (p. 357).
INTEGER
<opt_cat_id>
The ID to be used for referencing this material option category. This ID must be unique with respect to all material option category IDs previously defined in this analysis code but can and should be duplicates of material option category IDs used in other analysis codes.
CHARACTER STRING
<opt_cat_name>
The analysis code specific name for this material option category.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Material option categories must be uniquely defined for a specific analysis code. But, for the sake of data transfer the material option category IDs used should remain the same. For example, it would take two definition (“db_create_mtl_magics_defn”) calls to define a given material option category in both MSC Nastran and MSC.Marc, but the same material option category ID would be used in both calls. The IDs which should be used for specific material option categories are given below. If the material option category of interest does not exist in the following list, a new and unique ID should be used.Users and third-parties should define IDs in the range 20000 to 29999 to avoid conflicts with MSC-defined IDs.
 
<opt_cat_name>
<opt_cat_id>
Composite Failure Theory
1
Failure Criteria
2
Plastic Data Input
3
Yield Function
4
Hardening Rule
5
Creep Data Input
6
Elastic Data Input
7
Creep Law
8
Rate Dependency
9
Domain Type
10
Definition Type
11
Anisotropic Yield Criteria
12
Order of Polynomial
13
Strain Energy Potential
14
Orthotropic Yield Criteria
15
The PCL function used to define the material options is described below:
 
db_create_mtl_magics_options
(<analy_code_id>,<opt_id>,<opt_name>)
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<opt_id>
The ID to be used for referencing this material option. This ID must be unique with respect to all material option IDs previously defined in this analysis code but can and should be duplicate of material option IDs used in other analysis codes.
CHARACTER STRING
<opt_name>
The analysis code specific name for this material option.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Material options must be uniquely defined for a specific analysis code. But, for the sake of data transfer the material option IDs used should remain the same. For example, it would take two definition (“db_create_mtl_magics_options”) calls to define a given material option in both MSC Nastran and MSC.Marc, but the same material option ID would be used in both calls. The IDs which should be used for specific material options are given below. If the material option of interest does not exist in the following list, a new and unique ID should be used. Users and third-parties should define IDs in the range 20000 to 29999 to avoid conflicts with MSC-defined IDs
 
<opt_name>
<opt_id>
Not Applicable
1
Hill Failure Theory
2
Hoffman Failue Theory
3
Tsai-Wu Failure Theory
4
Maximum Strain Theory
5
Stress Failure Criteria
6
Strain Failure Criteria
7
Stress/Strain Curve
8
Hardening Slope
9
VonMises Yield Function
10
Tresca Yield Function
11
Mohr-Coulomb Yield
12
Drucker-Prager Yield
13
Isotropic Hardening
14
Kinematic Hardening
15
Combined Hardening
16
Tabular Creep Input
17
Creep Law 111
18
Creep Law 112
19
Creep Law 121
20
Creep Law 122
21
Creep Law 211
22
Creep Law 212
23
Creep Law 221
24
.
<opt_name>
<opt_id>
Creep Law 222
25
Creep Law 300
26
Parabolic Drucker-Prager
27
Perfectly Plastic
28
Maximum Stress Theory
29
None
30
Add
31
Deformation
32
Modified Drucker/Cap
33
ORNL
34
Cap Hardening
37
Compression
38
Tension
39
Shear
40
10 Cycle
41
100 Cycle
42
ORNL Hardening
43
Engineering Constants
44
[D] Matrix
45
Time
46
Frequency
47
Strain
48
Hyperbolic
49
Formula
50
Tabular
51
Prony
52
Test Data
53
First Order Polynomial
54
Second Order Polynomial
55
Third Order Polynomial
56
Fourth Order Polynomial
57
Fifth Order Polynomial
58
Sixth Order Polynomial
59
Polynomial
60
Ogden
61
Now specify which material options belong to which material option category. The PCL function described below performs this function.
 
db_create_mtl_allowable_magics
(<analy_code_id>, <cat_id>, <opt_cat_id>, <opt_ids>, <num_opts>)
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<cat_id>
INTEGER
<opt_cat_id>
The ID of the material option category.
INTEGER ARRAY
<opt_ids>
The <num_opts> IDs of all the material options grouped under this material option category.
INTEGER
<num_opts>
The number of material options grouped under this material option category.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
The material option categories are associated with the appropriate material categories and material models with the following PCL function.
  
db_create_mtl_magics
(<analy_code_id>, <analy_type_id>, <cat_id>, <model_id>, <opt_cat_ids>, <num_opt_cats>)
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<analy_type_id>
The ID of the analysis type. Analysis type IDs are described in Adding A New Analysis Preference (p. 357).
INTEGER
<cat_id>
The ID of the material category. See Material Categories, 529.
INTEGER
<model_id>
The ID of the material model. See Material Models, 532.
INTEGER ARRAY
<opt_cat_ids>
The <num_opt_cats> IDs of the material option categories to be associated with this material model under this material category.
INTEGER
<num_opt_cats>
The number of material option categories to be associated with this material model under this material category.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Material Property Words
To create material property words, first define the material words generically, if they have not already been defined, and then assign analysis code specific attributes to these material words such as an analysis code specific name and allowable field types. The function used to define new material words is described below.
 
db_create_matl_prop_defn
(<word_id>, <word_name> )
 
Input:
 
 
INTEGER
<word_id>
The ID used to reference this material property word. This ID must be unique with respect to all previously defined material property word IDs. Users and third-parties should define IDs in the range 20000 to 29999 to avoid conflicts with MSC-defined IDs.
CHARACTER STRING
<word_name>
The generic name of this material property word.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
The list of material property words defined by “load_generics()” is:
 
<word_name>
<word_id>
Reference Temperature
1
Elastic Modulus
2
Elastic Modulus 22
3
Elastic Modulus 33
4
Poisson Ratio
5
Poisson Ratio 23
6
Poisson Ratio 31
7
Shear Modulus
8
Shear Modulus 23
9
Shear Modulus 31
10
Poisson Ratio 13
13
Bulk Modulus
14
Lame Constant
15
Density
16
Conductivity
17
Conductivity 12
18
Conductivity 13
19
Conductivity 22
20
Conductivity 23
21
Conductivity 33
22
Specific Heat
23
Thermal Expansion Coeff
24
Thermal Expansion Coeff 22
25
Thermal Expansion Coeff 33
26
Thermal Expansion Coeff 12
27
Thermal Expansion Coeff 23
28
Thermal Expansion Coeff 31
29
Structural Damping Coeff
30
Emissivity
31
Rate Dependent Param D
1013
Rate Dependent Param p
1014
Dilation Angle
1016
Ratio of Flow Stresses
1017
Absolute Plastic Strain
1018
Exponent
1019
Yield Offset
1020
Material Cohesion
1023
Eccentricity Parameter
1024
Yield Surface Transition
1025
Surface Radius Parameter
1026
 
<word_name>
<word_id>
Hydrostatic Yield Stress
1027
Volumetric Plastic Strain
1028
Real Part of g1
1101
Imaginary Part of g1
1102
Value of a
1103
Real Part of k1
1104
Imaginary Part of k1
1105
Value of b
1106
Value of A
1201
Value of B
1202
Value of n
1203
Value of m
1204
Value of delta_H
1205
Value of R
1206
Coefficient C10
1301
Coefficient C20
1302
Coefficient C30
1303
Coefficient C40
1304
Coefficient C50
1305
Coefficient C60
1306
Coefficient C01
1311
Coefficient C02
1312
Coefficient C03
1313
Coefficient C04
1314
Coefficient C05
1315
Coefficient C06
1316
Coefficient C11
1321
Coefficient C21
1322
Coefficient C12
1323
Coefficient C31
1324
Coefficient C22
1325
Coefficient C13
1326
Coefficient C41
1327
Coefficient C32
1328
Coefficient C23
1329
Coefficient C14
1330
Coefficient C51
1331
Coefficient C42
1332
Coefficient C33
1333
Coefficient C24
1334
Coefficient C15
1335
Coefficient MU1
1401
Coefficient MU2
1402
Coefficient MU3
1403
Coefficient MU4
1404
Coefficient MU5
1405
Coefficient MU6
1406
Coefficient ALPHA_1
1411
Coefficient ALPHA_2
1412
Coefficient ALPHA_3
1413
Coefficient ALPHA_4
1414
Coefficient ALPHA_5
1415
Coefficient ALPHA_6
1416
Coupling Stiffness 22
96
Coupling Stiffness 23
97
Coupling Stiffness 33
98
 
<word_name>
<word_id>
Tension Stress Limit
99
Compression Stress Limit
100
Shear Stress Limit
101
Tension Stress Limit 22
102
Compression Stress Limit 22
103
Shear Stress Limit 23
104
Tension Stress Limit 33
105
Compression Stress Limit 33
106
Shear Stress Limit 31
107
Tension Strain Limit
108
Compression Strain Limit
109
Shear Strain Limit
110
Tension Strain Limit 22
111
Compression Strain Limit 22
112
Shear Strain Limit 23
113
Tension Strain Limit 33
114
Compression Strain Limit 33
115
Shear Strain Limit 31
116
Ht Ratio
117
Hardening Slope
120
Yield Point
121
Equivalent Yield Stress (J1=0)
122
Alpha
123
Beta
124
Stress 11 Yield Ratio
125
Stress 22 Yield Ratio
126
Stress 33 Yield Ratio
127
Stress 12 Yield Ratio
128
Stress 23 Yield Ratio
129
Stress 31 Yield Ratio
130
Internal Friction Angle
131
Bonding Shear Stress Limit
132
Interaction Term
133
Failure Index
134
Creep Reference Temperature
135
Creep Threshold Factor
136
Temperature Dependence Exponent
137
Primary Creep Stiffness
138
Primary Creep Damping
139
Secondary Creep Damping
140
Coefficient A
141
Coefficient B
142
Coefficient C
143
Coefficient D
144
Coefficient E
145
Coefficient F
146
Coefficient G
147
Interaction Term 23
148
Interaction Term 31
149
Stress/Strain Curve
503
Mass Propornl Damping
1001
2nd. Yield Stress
1011
Plastic Strain
1012
 
<word_name>
<word_id>
Stiffness Propornl Damping
1002
Fraction Critical Damping
1003
Composite Options Flag
37
Positive Definite Flag
38
Total Laminate Thickness
39
Number of Plies
40
Laminate Offset
41
Moisture Expansion Coeff 11
42
Moisture Expansion Coeff 22
43
Moisture Expansion Coeff 33
44
Moisture Expansion Coeff 12
45
Moisture Expansion Coeff 23
46
Moisture Expansion Coeff 31
47
Force Resultant (N1) per Temp
48
Force Resultant (N2) per Temp
49
Force Resultant (N12) per Temp
50
Moment Resultant (M1) per Temp
51
Moment Resultant (M2) per Temp
52
Moment Resultant (M12) per Temp
53
Stiffness 11
54
Stiffness 12
55
Stiffness 13
56
Stiffness 22
57
Stiffness 23
58
Stiffness 33
59
Stiffness 44
60
Stiffness 45
61
Stiffness 46
62
Stiffness 55
63
Stiffness 56
64
Stiffness 66
65
Stiffness 14
66
Stiffness 15
67
Stiffness 16
 
Stiffness 24
69
Stiffness 25
70
Stiffness 26
71
Stiffness 34
72
Stiffness 35
73
Stiffness 36
74
Stiffness 11
75
Stiffness 12
76
Stiffness 13
77
Stiffness 22
78
Stiffness 23
79
Stiffness 33
80
Membrane Stiffness 11
81
Membrane Stiffness 12
82
Membrane Stiffness 13
83
Membrane Stiffness 22
84
Membrane Stiffness 23
85
Membrane Stiffness 33
86
Bending Stiffness 11
87
Bending Stiffness 12
88
Bending Stiffness 13
89
 
<word_name>
<word_id>
Bending Stiffness 22
90
Bending Stiffness 23
91
Bending Stiffness 33
92
Coupling Stiffness 11
93
Coupling Stiffness 12
94
Coupling Stiffness 13
95
Coefficient D1
1421
Coefficient D2
1422
Coefficient D3
1423
Coefficient D4
1424
+Coefficient D5
1425
Coefficient D6
1426
SigmaYY/Strain Curve
2002
SigmaZZ/Strain Curve
2003
SigmaXY/Strain Curve
2004
SigmaYZ/Strain Curve
2005
SigmaZX/Strain Curve
2006
To assign analysis code specific attributes to the material word the following function should be used. 
 
db_create_matl_prop_alias
(<analy_code_id>, <analy_type_id>, <cat_id>, <model_id>, <word_id>, <word_name>, <table_type> )
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<analy_type_id>
The ID of the analysis type. Analysis type IDs are described in Adding A New Analysis Preference (p. 357).
INTEGER
<cat_id>
The ID of the material category. See Material Categories, 529.
INTEGER
<model_id>
The ID of the material model. See Material Models, 532.
INTEGER
<word_id>
The generic ID of the material word.
CHARACTER STRING
<word_name>
The analysis code specific name of the material word.
INTEGER
<table_type>
A flag specifying which type of fields can be referenced by this material word. The meaning of this flag is as follows:
0 = No type of field allowed.
1 = Stress dependent field allowed.
2 = Strain dependent field allowed.
3 = Strain dependent or strain and temperature dependent fields allowed.
4 = Temperature dependent fields allowed.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.
 
 
Material Records
The last step in defining material properties is to group the material property words into material property records, i.e., specify which material words are valid for a unique choice of material category, material model and material options. This task is accomplished with the following PCL function.
 
db_create_allowable_matl_prop
(<analy_code_id>, <analy_type_id>, <cat_id>, <model_id>, <opt_ids>, <word_ids>, <num_words> )
 
Input:
 
 
INTEGER
<analy_code_id>
The ID of the new analysis code. Analysis code IDs are described in Adding A New Analysis Preference, 454.
INTEGER
<analy_type_id>
The ID of the analysis type. Analysis type IDs are described in Adding A New Analysis Preference (p. 357).
INTEGER
<cat_id>
The ID of the material category. See Material Categories, 529.
INTEGER
<model_id>
The ID of the material model. See Material Models, 532.
INTEGER ARRAY
<opt_ids>
The IDs of the five material option choices for the possible five material option categories related to this material model under this material category by db_create_mtl_magics, 539. This array is blank filed and in the same order as the material option categories defined by db_create_mtl_magics. For example, if there are two material option categories defined with this material model under this material category and the choices are option_cat_1( 1, 2 ) and option_cat_2( 5, 6, 7 ) then the six calls needed to fully define this material record would have the <opt_ids> arrays of [1,5,0,0,0], [1,6,0,0,0], [1,7,0,0,0], [2,5,0,0,0], [2,6,0,0,0] and [2,7,0,0,0]. If some of these combinations were invalid, say choices 1 and 8 were not compatible, this fact can be expressed to Patran by either not making the function call with array [1,8,0,0,0] in it or by specifying zero material words ( <num_words> = 0 ) in this call. Material option IDs are further discussed in the Material Options and Material Option Categories, 534.
INTEGER ARRAY
<word_ids>
The <num_words> IDs of the material words which are valid for this specified combination of material category, material model and material options. See Material Property Words, 540 for more information.
INTEGER
<num_words>
The number of material words valid for the specified combination of material category, material model and material options. Zero signifies that this specified combination of material options is invalid.
Output:
 
 
INTEGER
<Return Value>
Status return value. The value will be 0 if the routine is successful.
Error Conditions:
 
None.