2.3 The Command Line¶
FEBio is started from a shell window (or the command prompt in Windows). The command line is the same for all platforms:
febio4 [-o1 [arg1] | -o2 [arg2] | ... ]
Where -o1, -o2 are options and arg1, arg2,... are additional arguments. The different options (of which most are optional) are given by the following list:
| command line option | description | argument |
|---|---|---|
| -i | Specify the FEBio input file. | feb file name |
| -r | Specify the FEBio restart file. | restart file or dump file |
| -g,-g1,-g2 | Debug flags | - |
| -p | Specify name of the FEBio plot file. | plot file name |
| -o | Specify the name of the FEBio log file. | log file name |
| -s | Specify the optimization input file. | optimization input file |
| -d | Run an FEBio diagnostic | diagnostic input file |
| -break | Set a breakpoint where FEBio will pause the run. | breakpoint |
| -dump[=n] | Activate restart option and (optionally) set dump file name | dump file name |
| -dump_stride[=n] | Set the dump interval. | - |
| -config | Specify the FEBio configuration file to use. | configuration file |
| -noconfig | Don't read configuration file. | - |
| -nosplash | Don't print the splash window to the screen on startup. | - |
| -import | Import a plugin file. | plugin file name |
| -silent | Run FEBio in silent mode, which suppresses screen output. | - |
| -task[=name] | Run an FEBio task | task input file |
| -info | Print febio version information to screen or file | (optional) output file name |
| -noappend | Do not append the log and plot files on restart. | - |
| -norun | Do not run FEBio. (Only process command line.) | - |
| -output_negative_jacobians[=n] | Specify the max nr of negative jacobians that will be printed. | - |
Table 1. List of command line options.
A more detailed description of these options follows.
-i The -i option is used to specify the name of the input file. The input file is expected to follow the format specifications as described in Chapter 3.
Example:
> febio4 -i input.feb
This is the most common way to start an FEBio run. However, FEBio allows the omission of the -i when only a filename is given.
> febio4 input.feb
On Windows, this allows for starting FEBio by double-clicking on an input file (assuming you have chosen FEBio as the default program to open .feb files). Note that if additional options are specified on the command line the -i must be present.
It is also allowed to omit the .feb extension for FEBio input files. If no extension is given, FEBio will assume that .feb is the file extension. Thus, the following command will run the file input.feb:
> febio4 input
-r The -r option allows you to restart a previous analysis. The filename that must follow this option is an FEBio restart input file or a dump file. The restart input file and dump file are described in more detail in Restarting a Run. The -i and -r options are mutually exclusive; only one of them may appear on the command line.
Example:
> febio4 -r file.feb
-g,-g1,-g2 The –g options run FEBio in debug mode, in which case FEBio will print more information to the log and plot files. See Section Debugging a Run for more information on running FEBio in debug mode.
Example:
> febio4 -i input.feb –g
-p The –p option allows the user to specify the name of the plot file. The plot file is a binary file that contains the main results of the analysis. FEBio usually provides a default name for this file; however, the user can override the default name using this option. See Section FEBio Output for more details on the output files generated by FEBio.
Example:
> febio4 -i input.feb –p out.xplt
-o The –o option allows the user to set the name of the log file. The log file will contain a record of the screen output that was generated during a run. FEBio usually provides a default name for this file (see Section FEBio Output), but the user can override it with this command line option.
Example:
> febio4 -i input.feb –o out.log
-s This option instructs FEBio to run a material parameter optimization on the specified input file. The optimization module is described in detail in Chapter 6. The –s option is followed by the optimization control file which contains among other things the parameters that need to be optimized. Note that the restart feature does not work with the optimization module.
Example:
> febio4 –i file.feb –s control.opt
-d This option will run a FEBio diagnostics. A diagnostic is a special type of test that can be used to verify an implementation. For example, the tangent diagnostic allows users to check the consistency between the material's stress and tangent implementations.
Example:
> febio4 –d diagnostic.feb
-break With this option a break point can be set which sets a time point or an event at which FEBio will interrupt the run and show the FEBio prompt. The following example sets a break point at time 1.0. FEBio will interrupt the run after the time step at time 1.0 is reached (i.e. has converged). (See section Setting break points for more information on setting break points.)
Example:
> febio4 –i file.feb –break 1.0
-dump It is possible to restart a previous run using the restart capability in FEBio. This is useful when a run terminates unexpectedly. If that happens, the user can restart the analysis from the last converged timestep. Before this feature can be used, the user must request the creation of a dump file. This file will store all the information that FEBio will need to restart the analysis. FEBio will usually provide a default name for the dump file, but the –dump command line option allows the user to override the default name for the dump file. See Section Restarting a Run and Chapter 5 for more details on how to use the restart feature.
Example:
> febio4 -i input.feb –dump out.dmp
To control when FEBio will write the dumpfile, the -dump command can be appended by a number that defines the dump level. See section Restarting a Run for more information.
-dump_stride Sets the interval between writing dump files. The default is 1 (although the dump level may affect this as well.) The following example will write a dump file after every 10 timesteps.
Example:
> febio4 -i input.feb –dump out.dmp -dump_stride=10
-config As of version 1.2, FEBio uses a configuration file to store platform specific settings. Usually FEBio assumes that the location for this configuration file is the same as the executable. However, the user can specify a different location and filename using the –config command line option. If the user does not have a configuration file or does not wish to use one, this can be specified using the –noconfig option. More details on the configuration file can be found in Section The Configuration File and Chapter 7.
Example:
> febio4 -i input.feb –config C:$\backslash$path$\backslash$to$\backslash$febio.xml
-noconfig Do not read and process the FEBio configuration file. FEBio will start with its default configuration.
-nosplash When the –nosplash command is entered on the command line, FEBio will not print the welcome message to the screen. This is useful when calling FEBio from another application and when the user wishes to suppress any screen output from FEBio. Other options for suppressing output can be set in the control section of the FEBio input file (see Section Control Parameters).
Example:
> febio4 -i input.feb –nosplash
-import This command will load the plugin that is specified following this command line option. Although it is more convenient to list plugins in the FEBio configuration file, this option allows users to load a plugin from the command line, if such a need would arise.
Example:
> febio4 –import myplugin.dll
-silent When the –silence option is specified on the command line, FEBio will not generate any output to the screen. Unless explicitly instructed not to, FEBio will still create a log file which will have the convergence information.
Example:
> febio4 -i input.feb –silent
-task FEBio will always run a task. The default task is to solve a forward model defined by the input file specified using the -i command line option. However, other tasks are available, such as optimization and restart, as well as user-created tasks created in FEBio plugins. The name of the task is defined after an equal sign (=). An optional task control file can be specified as well. For instance, an alternative way for running an optimization problem is as follows.
Example:
> febio4 -i input.feb –task=optimize control.opt
-info Prints version information to the screen.
-noappend Do not append the log and plot file on restart. When restarting an analysis, FEBio will append the log and plot files with new data. However, when using this flag, new log and plot files will be generated for the run.
-norun Do not run FEBio. Only command line is processed. For instance, to get the version info from FEBio without running it, use the following command.
> febio4 -info -norun
-output_negative_jacobians Sets whether FEBio will output any negative Jacobians. A negative Jacobian is often an indication of a problem during the solution process and knowing where these negative Jacobians occurred may be helpful for debugging. By default, FEBio will only report that negative Jacobians happened, but won't print any other information. The command can also be appended by a number that indicates the max number of Jacobians will be printed.
> febio4 -i input.feb –output_negative_jacobians=100