# 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.
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

Table 1: Valid property identifiers.
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.