This code has been used for the numerical experiments in the thesis "Numerical homogenization of time-dependent Maxwell's equations with dispersion effects" by Jan Philip Freese, see https://www.doi.org/10.5445/IR/1000129214.

This code has been used for the numerical experiments in the thesis "Numerical homogenization of time-dependent Maxwell's equations with dispersion effects" by Jan Philip Freese, see https://www.doi.org/10.5445/IR/1000129214.

# Readme
This code was used for the numerical experiments of the PhD thesis "Numerical homogenization of time-dependent Maxwell's equations with dispersion effects" by P. Freese (cf. Section 7.2, Section 7.3) https://www.doi.org/10.5445/IR/1000129214. 
The computations are done in C++ using the Finite Element library deal.II.

## Requirements
- In order to run the code you need **deal.II** (release 9.1.1), cf. https://www.dealii.org/9.1.1
- For the experiments on the macroscopic level (Section 7.3) you need to compile deal.II using **Trilinos** (version 12.17) and **p4est** (version 2.2), cf. https://www.dealii.org/9.1.1/external-libs/trilinos.html and https://www.dealii.org/9.1.1/external-libs/p4est.html
- To get the full functionality of the scripts a **Bash** shell has to be used and at least **cmake** (version 3.13.0) is needed
- For the visualization of the data you need **Matlab** (version R2020a Update 2) and **Paraview** (version 5.8.1-RC1)

## Structure
The structure is as follows: 

- The folder **executables** contains Bash scripts for all figures and tables separately. All figures from Section 7.2 may be computed using the `compute_all_micro_figures_and_tables.sh` at ones. Similarly, the figures from Section 7.3 are computed using the `compute_all_macro_figures_and_tables.sh` script. Moreover, the `distclean.sh` script runs the `deal.II` distclean command in all programs.
- The folder **matlab_plot_files** contains Matlab scripts for the convergence plots and related tables
- The folder **paraview_plot_files** contains Paraview states to generate the solution plots
- In **programs** the actual source code is stored within three different programs that are
    - **hmm_for_Maxwell_conductivity_memory_variable:** Code that applies the Heterogeneous Multiscale Method combined with the memory variable technique as explained in Section 6.2.3
    - **hmm_for_Maxwell_conductivity_recursive_convolution:** Code that applies the Heterogeneous Multiscale Method combined with the recursive convolution technique as explained in Section 6.2.2
    - **microproblem_conductivity:** Code that solves the microscopic cell problems
- In **results** the results of the computations are stored according to the sub structure of the **programs** folder


## Howto
In order to run the program, open a terminal session in the folder **executables** and run one of the Bash scripts providing at least the additional argument:

-  **Number of kernels (-n)**: One should usually use one job for each processor core on the machine

Use a command like

```bash
    bash figure*.sh -n number_of_kernels
```
It may be mandatory to provide the location of your deal.II installation as well. This is done by providing another argument:

-  **Path to deal (-D)**: Path to the deal.II installation

Use a command like

```bash
    bash figure*.sh -n number_of_kernels -D path_to_deal
```

If you can not execute the Bash scripts, you have to build the program and copy/edit the config/source files yourself.  Still, the necessary information is found in the bash scripts, so just use a text editor to open those files and execute the steps by hand.

### Example
If you unpack this code within the **examples** folder of **deal.II** you can simply use the following example code to run the Bash script (generating data for Figure 7.2 and Table 7.1 with 4 kernels)

```bash
    bash figure_7_2_table_7_1.sh -n 4 -D ../../../../
``` 
## Visualization

### Matlab
The Matlab scripts are used to generate the plots and tables. The tables are directly prompted to the Matlab output.

### Paraview
To load the state files in Paraview, select `File->Load State...`. Select the respective `.pvsm` file of the figure you want to plot. As `Load State Data File Options` choose `Search files under specified directory` and select the `results` folder. Paraview should find the files itself.

## Remarks
- The scripts `figure_7_19_table_7_9.sh` and `figure_7_21_table_7_10.sh` save reference solutions that are used to compute the errors between different levels of refinement. These solutions are stored in `programs/hmm_for_Maxwell_conductivity_recursive_convolution/data/`. If you want to run these scripts a second time you either have to delete the solutions (and compute the solutions again) or you have to set the `Output.Reference_Solution` flag in the respective config file in `programs/hmm_for_Maxwell_conductivity_recursive_convolution/config_files/` to false (which makes the computation even faster).
- Be aware that, depending on your computer, the computations may take several hours or days.

Readme
This code was used for the numerical experiments of the PhD thesis "Numerical homogenization of time-dependent Maxwell's equations with dispersion effects" by P. Freese (cf. Section 7.2, Section 7.3) https://www.doi.org/10.5445/IR/1000129214.
The computations are done in C++ using the Finite Element library deal.II.
Requirements

In order to run the code you need deal.II (release 9.1.1), cf. https://www.dealii.org/9.1.1
For the experiments on the macroscopic level (Section 7.3) you need to compile deal.II using Trilinos (version 12.17) and p4est (version 2.2), cf. https://www.dealii.org/9.1.1/external-libs/trilinos.html and https://www.dealii.org/9.1.1/external-libs/p4est.html
To get the full functionality of the scripts a Bash shell has to be used and at least cmake (version 3.13.0) is needed
For the visualization of the data you need Matlab (version R2020a Update 2) and Paraview (version 5.8.1-RC1)

Structure
The structure is as follows: 

The folder executables contains Bash scripts for all figures and tables separately. All figures from Section 7.2 may be computed using the compute_all_micro_figures_and_tables.sh at ones. Similarly, the figures from Section 7.3 are computed using the compute_all_macro_figures_and_tables.sh script. Moreover, the distclean.sh script runs the deal.II distclean command in all programs.
The folder matlab_plot_files contains Matlab scripts for the convergence plots and related tables
The folder paraview_plot_files contains Paraview states to generate the solution plots
In programs the actual source code is stored within three different programs that are

hmm_for_Maxwell_conductivity_memory_variable: Code that applies the Heterogeneous Multiscale Method combined with the memory variable technique as explained in Section 6.2.3
hmm_for_Maxwell_conductivity_recursive_convolution: Code that applies the Heterogeneous Multiscale Method combined with the recursive convolution technique as explained in Section 6.2.2
microproblem_conductivity: Code that solves the microscopic cell problems

In results the results of the computations are stored according to the sub structure of the programs folder

Howto
In order to run the program, open a terminal session in the folder executables and run one of the Bash scripts providing at least the additional argument:

Number of kernels (-n): One should usually use one job for each processor core on the machine

Use a command like
    bash figure*.sh -n number_of_kernels
It may be mandatory to provide the location of your deal.II installation as well. This is done by providing another argument:

Path to deal (-D): Path to the deal.II installation

Use a command like
    bash figure*.sh -n number_of_kernels -D path_to_deal
If you can not execute the Bash scripts, you have to build the program and copy/edit the config/source files yourself.  Still, the necessary information is found in the bash scripts, so just use a text editor to open those files and execute the steps by hand.
Example
If you unpack this code within the examples folder of deal.II you can simply use the following example code to run the Bash script (generating data for Figure 7.2 and Table 7.1 with 4 kernels)
    bash figure_7_2_table_7_1.sh -n 4 -D ../../../../
Visualization
Matlab
The Matlab scripts are used to generate the plots and tables. The tables are directly prompted to the Matlab output.
Paraview
To load the state files in Paraview, select File->Load State.... Select the respective .pvsm file of the figure you want to plot. As Load State Data File Options choose Search files under specified directory and select the results folder. Paraview should find the files itself.
Remarks

The scripts figure_7_19_table_7_9.sh and figure_7_21_table_7_10.sh save reference solutions that are used to compute the errors between different levels of refinement. These solutions are stored in programs/hmm_for_Maxwell_conductivity_recursive_convolution/data/. If you want to run these scripts a second time you either have to delete the solutions (and compute the solutions again) or you have to set the Output.Reference_Solution flag in the respective config file in programs/hmm_for_Maxwell_conductivity_recursive_convolution/config_files/ to false (which makes the computation even faster).
Be aware that, depending on your computer, the computations may take several hours or days.