prop2plot
Introduction¶
This Python script allows the post-processing of several homogenization result files of hres type (containing one or more homogenization results, for example at specified temperatures), generated by the version 6.0 of HOMAT. The purpose of this script is to extract homogenization results from a given set of files and compile them into a tabulated selection of effective properties in TAB (.tsv) or comma (.csv) separated ASCII files, suitable for plotting/visualization using a tool of your choice, such as Gnuplot or Matplotlib.
Execution¶
prop2plot
supports an extensive list of command-line parameters. All arguments are case-sensitive. To see an overview, call the help as follows:
prop2plot -h
This will generate the following output:
usage: prop2plot [-h] [-o OUTPUT] [-p PROP [PROP ...]] [-f {csv,tsv}] [-T]
[-l] [-E] [-v]
hresfiles [hresfiles ...]
positional arguments:
hresfiles HOMAT result files
optional arguments:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
Basename for the output file(s)
-p PROP [PROP ...], --props PROP [PROP ...]
Property to extract. Allowed values are Emod, Gmod,
Cmod, Ctens, Eigen, Nu, Dens, Cond, Alpha, Perm, ALL.
Defaults to Emod, Gmod, Nu, Cond and Perm.
-f {csv,tsv}, --outformat {csv,tsv}
Output format. Defaults to tsv.
-T, --fulltensor Output all tensor components, where it is appropriate.
-l, --locCS Use quantities in the local coordinate system.
-E, --princ Output principal values and directions of 2nd order
tensors. Applies to Alpha, Eigen, Cond and Perm.
-v, --verbose Talk more.
The most basic usage-scenario is calling the script with one (or multiple) hres-files without any optional arguments, such as
prop2plot file.hres
or, with multiple files,
prop2plot file1.hres file2.hres
or
prop2plot file*.hres
where *
matches any sequence of characters. In this case the script will extract default set of properties (cf. Sec. Properties) in the RVE coordinate system (cf. Sec. Coordinate systems) and write TAB-separated (.tsv) files as output (cf. Sec. File formats). The name of the resulting files will be BASENAME_PROP.tsv
, where BASENAME
is derived from the name of the first file read (cf. Sec. Naming conventions) and PROP
is the name of the property it contains.
Without going into detail at this point, it should be noted that multiple properties can be selected using the -p
or -props
options. This leads to certain idiosyncrasies in the execution syntax of prop2plot
. While the following calls are correct,
prop2plot file.hres -p Emod Gmod
prop2plot -p Emod Gmod -v file.hres
this example
prop2plot -p Emod Gmod file.hres
produces the following error:
usage: prop2plot [-h] [-o OUTPUT] [-p PROP [PROP ...]] [-f {csv,tsv}] [-T]
[-l] [-E] [-v]
file.hres [file.hres ...]
prop2plot: error: argument -p/--props: invalid choice: 'file.hres' (choose from 'Emod', 'Gmod', 'Cmod', 'Ctens', 'Eigen', 'Nu', 'Dens', 'Cond', 'Alpha', 'Perm')
The reason is that file.hres
is considered to be an invalid property request. A correct version of this example is
prop2plot -p Emod Gmod -- file.hres
where the --
operator signifies the end of the list of optional parameters.
Properties¶
The properties to extract are selected using the -p
or -props
options. Any number of properties can be extracted in a single run by specifying their names separated by spaces, such as -p Cmod Gmod
or --props Cmod Gmod
. Valid property names are summarized in Tab. 1
name | description | analysis type | modifiers |
---|---|---|---|
Emod | orthotropic Young's moduli | MECHAN , THELAS , THERMEC | -l |
Gmod | orthotropic shear moduli | MECHAN , THELAS , THERMEC | -l |
Nu | orthotropic Poisson's ratios | MECHAN , THELAS , THERMEC | -l |
Cmod | cubic elastic constants, Zener anisotropy | MECHAN , THELAS , THERMEC | |
Ctens | full elastic stiffness tensor | MECHAN , THELAS , THERMEC | -l |
Dens | density, heat capacity and specific heat | THERMAL , THERMEC | |
Cond | thermal conductivity | THERMAL , THERMEC | -l , -T , -E |
Alpha | thermal expansion coefficients | THERMEC , THELAS | -l , -E |
Eigen | eigenstrains | THERMEC , THELAS | -l , -E |
Perm | permeability | STOKES | -l , -T , -E |
ALL | all of the above | any | -l , -T , -E |
A detailed description based on examples is given below.
Emod
, Gmod
and Nu
¶
The orthotropic Young's and shear moduli as well as the corresponding Poisson's ratios are easily extracted, as shown below for the following hres-file:
| Shear moduli | G_12 | G_13 | G_23 |
| | | | |
| | 3.070664E+03 | 4.029400E+03 | 4.029401E+03 |
| | | | |
| mean value | DG_12 | DG_13 | DG_23 |
| | | | |
| 3.709821E+03 | -17.23 | 8.61 | 8.61 |
|--------------------------------------------------------------------------|
| | | | |
| Young moduli | E_1 | E_2 | E_3 |
| | | | |
| | 1.250458E+04 | 1.250456E+04 | 4.340227E+04 |
| | | | |
| mean value | DE_1 | DE_2 | DE_3 |
| | | | |
| 2.280380E+04 | -45.16 | -45.16 | 90.33 |
|--------------------------------------------------------------------------|
| | | | |
| Poisson coefficients | nu_12 | nu_13 | nu_23 |
| | | | |
| | 3.106013E-01 | 2.727762E-01 | 2.727764E-01 |
| | | | |
| mean value | Dnu_12 | Dnu_13 | Dnu_23 |
| | | | |
| 2.853846E-01 | 8.84 | -4.42 | -4.42 |
Calling prop2plot
with -p Emod
produces a result file with the following content
# Layer Temp E_x E_y E_z Mean D1 (%) D2 (%) D3 (%)
#
1 - 1.2505e+04 1.2505e+04 4.3402e+04 2.2804e+04 -4.5164e+01 -4.5165e+01 9.0329e+01
-p Gmod
# Layer Temp G_xy G_xz G_yz Mean D1 (%) D2 (%) D3 (%)
#
1 - 3.0707e+03 4.0294e+03 4.0294e+03 3.7098e+03 -1.7229e+01 8.6144e+00 8.6144e+00
-p Nu
# Layer Temp nu_xy nu_xz nu_yz Mean D1 (%) D2 (%) D3 (%)
#
1 - 3.1060e-01 2.7278e-01 2.7278e-01 2.8538e-01 8.8360e+00 -4.4180e+00 -4.4180e+00
Along with the extracted properties, each results-file contains information about the homogenized layer, the temperature (if provided, else it is marked missing by a -
), as well as the property's mean value and the deviations of each component from this mean value in %.
Cmod
¶
The following example shows Eut30_Tsup_14.2s.hres
with cubic elastic and engineering constants for tree temperatures:
| Elastic moduli | C_11 | C_12 | C_44 |
| | | | |
| 550.00 | 8.404616E+04 | 4.900426E+04 | 2.394352E+04 |
| 560.00 | 8.336865E+04 | 4.867757E+04 | 2.377199E+04 |
| 571.50 | 8.258893E+04 | 4.830161E+04 | 2.357456E+04 |
| | | | |
| Eng. moduli | E | nu | Zener coeff.|
| | | | |
| 550.00 | 4.794466E+04 | 3.680011E-01 | 1.366565E+00 |
| 560.00 | 4.747588E+04 | 3.683214E-01 | 1.370496E+00 |
| 571.50 | 4.693630E+04 | 3.686962E-01 | 1.375118E+00 |
The extracted results using -p Cmod
are as follows:
# Time Layer Temp C11 C12 C44 E nu Zener
#
1.4200e+01 1 550.00 8.6767e+04 4.8954e+04 2.6723e+04 5.1451e+04 3.6070e-01 1.4134e+00
1.4200e+01 1 560.00 8.6129e+04 4.8638e+04 2.6567e+04 5.1021e+04 3.6091e-01 1.4173e+00
1.4200e+01 1 571.50 8.5394e+04 4.8274e+04 2.6388e+04 5.0526e+04 3.6115e-01 1.4218e+00
Note that a timestamp (14.2s) was automatically detected in the filename, causing prop2plot
to add a Time
-column to the results (cf. Sec. Naming conventions)
Ctens
¶
This options extracts all 21 components of the (symmetrized) stiffness tensor. -T
is implied.
Dens
¶
From a thermal homogenization analysis that provides the heat capacity, the density and the specific heat in the hres-file,
| heat capacity | rhocp | | |
| | | | |
| | 6.500015E-02 | | |
| | | | |
| Density | dens | | |
| | | | |
| | 2.062501E-03 | | |
| | | | |
| specific heat | cp | | |
| | | | |
| | 2.750264E+01 | | |
prop2plot with -p Dens
extracts:
# Layer Temp cp dens rhocp
#
1 - 2.7503e+01 2.0625e-03 6.5000e-02
Alpha
, Eigen
¶
For the effective thermal expansions and eigenstrains prop2plot
extracts all components available in the hres-file and computes the mean of the diagonal components as well as their deviation from this mean in percent. The following example shows a hres-file containing thermal expansion data for two temperatures:
| thermal expansion | alpha_xx | alpha_yy | alpha_zz |
| | | | |
| 800.00 | 1.265114E-05 | 1.240363E-05 | 1.100857E-05 |
| 1100.00 | 1.430439E-05 | 1.403192E-05 | 1.200152E-05 |
| | | | |
| mean value | Dal_xx | Dal_yy | Dal_zz |
| | | | |
| 1.202111E-05 | 5.24 | 3.18 | -8.42 |
| 1.344594E-05 | 6.38 | 4.36 | -10.74 |
The extracted result using the -p Alpha
option is as follows:
# Layer Temp alpha_xx alpha_yy alpha_zz Mean D1 (%) D2 (%) D3 (%)
#
1 800.00 1.2651e-05 1.2404e-05 1.1009e-05 1.2021e-05 5.2410e+00 3.1820e+00 -8.4230e+00
1 1100.00 1.4304e-05 1.4032e-05 1.2002e-05 1.3446e-05 6.3844e+00 4.3580e+00 -1.0742e+01
Cond
, Perm
¶
By default, only the diagonal components of the thermal conductivity and (Darcy) permeability tensors are extracted. To get the diagonal and off-diagonal components, use the -T
option. Given the following effective 2D conductivity tensor in the hres-file,
| | |
| heat conductivity | k_i1 | k_i2 | k_i3 |
| | | | |
| k_1j | 6.776877E-01 | 1.803914E-12 | |
| k_2j | 1.109493E-11 | 4.272344E-01 | |
| | | | |
| mean value | Dk_x | Dk_y | Dk_z |
| | | | |
| 5.524610E-01 | 22.67 | -22.67 | 0.00 |
prop2plot
the options -p Cond -f csv
extracts the following (in csv-format):
# Layer,Temp,kxx,kyy,mean,D1 (%),D2 (%)
#
1,-,6.7769e-01,4.2723e-01,5.5246e-01,2.2667e+01,-2.2667e+01
In addition to the layer number and temperature (which was not given), you get the diagonal values of the conductivity tensor, their mean value as well as the deviations from the mean in %. Using the options -p Cond -T
you obtain from the same hres-file (in TAB-format):
# Layer Temp kxx kyy kxy
#
1 - 6.7769e-01 4.2723e-01 6.4494e-12
Here you find the diagonal and off-diagonal components of the symmetrized effective conductivity tensor.
Coordinate systems¶
By default, HOMAT outputs all results in the coordinate system of the representative volume elements (RVE); however, output in a different coordinate system (referred to as local) can be requested. prop2plot
follows these defaults by extracting properties in the RVE coordinate system. If properties in a local coordinate system are available in a hres-file, they can be extracted by specifying the -l
or --localCS
options. Given, for example, a hres-file containing the following
| Young moduli | E_x | E_y | E_z |
| | | | |
| | 4.001726E+03 | 5.744051E+03 | 4.086288E+03 |
| | | | |
| mean value | DE_x | DE_y | DE_z |
| | | | |
| 4.610688E+03 | -13.21 | 24.58 | -11.37 |
and
| local Young moduli | E_1 | E_2 | E_3 |
| | | | |
| | 1.189772E+03 | 2.805115E+03 | 9.700572E+02 |
| | | | |
| mean value | DE_1 | DE_2 | DE_3 |
| | | | |
| 1.654981E+03 | -28.11 | 69.50 | -41.39 |
prop2plot -p Emod
will produce
# Time Layer Temp E_x E_y E_z Mean D1 (%) D2 (%) D3 (%)
#
7.2000e+00 1 574.61 4.0017e+03 5.7441e+03 4.0863e+03 4.6107e+03 -1.3208e+01 2.4581e+01 -1.1374e+01
while prop2plot -p Emod -l
will produce
# Time Layer Temp E_1 E_2 E_3 Mean D1 (%) D2 (%) D3 (%)
#
7.2000e+00 1 574.61 1.1898e+03 2.8051e+03 9.7006e+02 1.6550e+03 -2.8110e+01 6.9495e+01 -4.1386e+01
Note that the properties in the RVE coordinate system have the indices x, y and z, while the properties in the local coordinate system have the indices 1, 2 and 3.
Principal values and directions¶
For properties that are 2nd order tensors (thermal expansion, eigenstrain, conductivity, thermal conductivity and (Darcy) permeability) prop2plot
can obtain principal values (eigenvalues) and the corresponding principal directions (eigenvectors) using the option -E
, or its long form --princ
. These quantities are directly computed from the symmetrized tensors, i.e., not read from the hres-file. Given a hres-file with the permeability tensor
| permeability tensor | P_X | P_Y | P_Z |
| | | | |
| comp. X | 3.978707E+00 | -1.761722E-01 | 2.183453E-01 |
| comp. Y | -1.763042E-01 | 4.676568E+00 | -1.069704E-01 |
| comp. Z | 2.186943E-01 | -1.068524E-01 | 3.893716E+00 |
| | | | |
|--------------------------------------------------------------------------|
| | | | |
| princ. perm. R_ani | P_1 | P_2 | P_3 |
| | | | |
| 8.42647E-01 | 4.748041E+00 | 4.088358E+00 | 3.712592E+00 |
|--------------------------------------------------------------------------|
| | | | |
| unit vector - P_1 | E1_1 | E2_1 | E3_1 |
| | | | |
| | 2.695531E-01 | -9.446232E-01 | 1.871579E-01 |
| | | | |
| unit vector - P_2 | E1_2 | E2_2 | E3_2 |
| | | | |
| | 7.127248E-01 | 3.263942E-01 | 6.208786E-01 |
| | | | |
| unit vector - P_3 | E1_3 | E2_3 | E3_3 |
| | | | |
| | 6.475836E-01 | 3.396768E-02 | -7.612369E-01 |
prop2plot -p Perm -E
will compute the following principal values and directions (which, of course, match the ones provided in the hres-file):
# Layer Temp B_1 B_2 B_3 E1_1 E1_2 E1_3 E2_1 E2_2 E2_3 E3_1 E3_2 E3_3
#
1 - 4.7480e+00 4.0884e+00 3.7126e+00 -2.6955e-01 9.4462e-01 -1.8716e-01 7.1272e-01 3.2639e-01 6.2088e-01 -6.4758e-01 -3.3968e-02 7.6124e-01
File formats¶
For the output of the extracted properties prop2plot
creates ASCII files with either TAB- or comma-separated values. By default, the TAB-separated (.tsv) format is adopted. This can be explicitly changed by calling prop2plot
with -f csv|tsv
or --outformat csv|tsv
.
Naming conventions¶
The name of the resulting file(s) has the form BASENAME_PROP.tsv
, where BASENAME
is either given explicitly via the -o
/ --output
options or derived from the name of the first hres-file read. PROP
is the name of the property it contains. For example, the command
prop2plot file.hres -o myresultname -p Emod
produces a file called myresultname_Emod.tsv
. The command
prop2plot file.hres nextfile.hres -p Nu
results in file_Nu.tsv
.
If the -l
or --locCS
options are provided, _loc
is attached to the filename, i.e.,
prop2plot file.hres -o myresultname -p Emod -l
produces a file called myresultname_Emod_loc.tsv
.
Filenames of the form name_time.hres
where time
is a time in seconds, such as 0.5s
or 2s
are treated separately. In this case the name
part serves as BASENAME
and a Time
-column is added to the results file. A typical application of this feature is the post-processing of the thermo-mechanical properties of microstructures computed with MICRESS during a solidification process.
Other options¶
-h
or --help
print a help message.
-v
produces more verbose output
Problems and Solutions¶
prop2plot
exited normally, but no output is produced¶
This usually means, that your hres-file does not contain the requested property. Solution: Inspect your hres-file; alternatively, rerun prop2plot
without any options or with -p ALL
to get everything that can be extracted from your hres-file.
The output is not sorted the way I want¶
prop2plot
processes files in the order they were read. This is the order you see in the results file. Solution: Supply the files in the order you want manually, or, if you rely on globbing (such as *.hres
), make sure that the filenames imply the order you prefer. Note, that using typical lexicographical ordering, file10.hres
will precede file2.hres
. To circumvent this issue, it is recommended to use an appropriate padding, such as file001.hres
.