4C Simulation

The basic command to execute 4C is (relative to the build directory)

./4C <input_file> <output_basename>

The input file is commonly a file with the suffix .4C.yaml, and it is commonly created by a preprocessing step, which is explained in detail in Preprocessing.

The <output_basename> should not have any suffix. Output generated by 4C consists at least of one file named <output_basename>.control. If further output has been requested, a number of further files are created. The file names are all given in the *.control file.

These results in the output files are by default stored in a proprietary format. However, output data can also be stored in a format that is readable by other programs. For further information, see Postprocessing.

All available options when starting 4C from the command line are shown by an output of ./4C --help:

4C - Multiphysics 
Comprehensive Computational Community Code 


Usage: [OPTIONS] [input] [output] [io_pairs...]


POSITIONALS:
  input TEXT                  Name of the input file, including the suffix 

  output TEXT                 Prefix of your output files. 

  io_pairs TEXT ...           More pairs of simulation <input> and <output> names. Only 
                              necessary when using nested parallelism with multiple groups and 
                              separate input files. 


OPTIONS:
  -h,     --help              Print this help message and exit 

  -p,     --parameters        Dumps information about the parameters for consumption by 
                              additional tools. 

  -i,     --interactive       4C waits at the beginning for keyboard input. Helpful for 
                              parallel debugging when attaching to a single job. 

          --ngroup INT:POSITIVE 
                              Specify the number of groups for nested parallelism. (default: 1) 

          --glayout           Specify the number of processors per group. Comma-separated list 
                              without spaces, e.g. --glayout=<a>,<b>. 
                              Argument --ngroup is mandatory if a glayout is provided. 
                              (default: equal distribution) 

          --nptype            Specify nested parallelism type: 
                              separateInputFiles|everyGroupReadInputFile| 
                              nestedMultiscale|diffgroup<N> 
                              Must be set if --ngroup > 1. 
                              'diffgroupx' can be used to compare vectors/matrices/results 
                              between two separate (serial/parallel) 4C runs; x must be 0 and 1 
                              for the respective run 

          --restart           Restart the simulation from step <y>. Accepts a non-negative 
                              integer or 'last_possible'. 
                              If nested parallelism with separate input files is used, each 
                              group can have a different restart step defined as a 
                              comma-separated list, e.g., --restart=<a>,<b>. 

          --restartfrom       Restart the simulation from the files prefixed with 
                              <restart_file_name>. 
                              If nested parallelism with separate input files is used, each 
                              group can have a different file prefix defined as a 
                              comma-separated list. 

Running examples

In tests/input_files a huge number of test examples are available. For example,

./4C tests/input_files/f2_drivencavity20x20_drt.4C.yaml xxx

runs the 2d fluid driven cavity example and writes the output to files beginning with xxx. You can also run the code in parallel with the mpirun command like this:

mpirun -np 1 ./4C tests/input_files/f2_drivencavity20x20_drt.4C.yaml xxx

Restarting an analysis

For restarting an analysis one has to provide restart information in the first simulation by including the parameter RESTARTEVERY <numsteps> in the relevant section, such that the information is written every numsteps step.

In the second simulation, no additional parameters have to be included. The information that it is a restart, is given on the command line:

./4C <restart_input_file> <output_basename> [--restartfrom=<restart_file_basename>] --restart=<step>

Here, one has to provide the step at which the restart is started from the previous simulation. Note that for a successful restart from step n, there must be a field entry at step n, followed by a result entry at step n, for all relevant fields. If --restart=last_possible, the last possible restart step is detected automatically. If the parameter --restartfrom is given, the initial configuration is read from this simulation, otherwise it is read from <output_basename>. In the latter case the filename of the new output is the same with an appended number, e.g., outfile-1.

Note

If you set --restart=0, a regular run is performed and the <--restartfrom> argument is ignored.
The parameters RESTART and RESTARTTIME in the PROBLEM TYPE section are not needed anymore, and will probably vanish soon.
The parameter MAXTIME indicates the maximum time of all simulations, it is NOT a step time, so be aware that MAXTIME in the subsequent simulation must be larger than in the first one.
The parameter TIMEINIT can be 0 also in the subsequent simulation, it is not used, since the initial time is defined by the restart.