2.4 The FEBio Prompt

The FEBio prompt is shown when you start FEBio without any command arguments (referred to as interactive mode), or when a run is interrupted either by the user (using ctrl+c ¹; See Section Interrupting a Run for more details), or by reaching a breakpoint (referred to as break mode). The FEBio prompt will look something like this:

febio>

You can now enter one of the following commands. Note that some commands are only available in a specific mode (either interactive or break mode). Also see additional comments below.

command line option	description	argument	interactive	break
break	Add a breakpoint, which stops FEBio at a particular point.(1)	breakpoint	✓	✓
breaks	Print a list of breakpoints.	-	✓	✓
clear	Clears one or more breakpoints.	breakpoint	✓	✓
config	Load (or reload) configuration file.	configuration file	✓
cont	Continue the current task	-		✓
conv	Force conversion of the current time step. (2)	-		✓
debug	Toggle debug mode (3)	[on/off]	✓	✓
events	Print a list of events	-	✓	✓
fail	Force the current time step to fail. (4)	-		✓
help	Print a list of available commands	-	✓	✓
import	Import a plugin file	plugin file name	✓
out	Output to file the current stiffness matrix and right-hand side	[-txt]		✓
plot	Write the current model state to the plot file. (5)	-		✓
plugins	Print a list of plugins.	-	✓	✓
print	Print the value of an internal variable. (6)	variable name		✓
quit	Stop the current model or exit of no model is running	-	✓	✓
restart	Toggle the restart flag. (7)	-		✓
run	Run a febio input file. (8)	(command line options)	✓
set	sets certain model and configuration variables. (9)	variable name (space) value		✓
svg	Write the sparse matrix profile to an svg file.	svg file name		✓
time	Print progress time statistics.	-		✓
unload	Unload a plugin from FEBio.	plugin name	✓
version	Print version information.	-	✓	✓
where	Prints the current callback event	-		✓
list	Lists all the factory classes (10)	(command line options)	✓	✓

Table 1. List of options for the FEBio command prompt.

Comments:

1. A breakpoint is a particular time point or an event at which FEBio will pause the run. See section Setting break points for more details on break points.

2. The force command is useful, for example, when a time step is having difficulty satisfying the convergence criteria. The user can then manually force the convergence of the time step. However, if the convergence difficulties are due to instabilities, forcing a time step to converge could cause the solution to become unstable or even incorrect. Also be aware that even if the solution recovers on later timesteps, the manually converged step might be incorrect.

3. The debug command toggles the debug flag. Adding on (off) will turn the debug mode on (resp. off). In debug mode, FEBio will store additional information to the log and plot file that could be useful in debugging the run. It is important to note that since FEBio will store all non-converged states to the plot file, this file may become very large in a short number of time steps. See Section Debugging a Run for more details on debugging.

4. If the current time step is not converging and if the auto-time stepper is enabled, the fail command will stop the current time step and retry it with a smaller time step size. If the auto-time stepper is not enabled, the fail command will simply exit the application.

5. The plot command is useful when you want to store the non-converged state at the current iteration. Note that this command only stores the state at the current iteration. If you turn on debug mode, all the iterations are stored to the plot file.

6. The following variables can be printed.

nnz Number of nonzeroes in global stiffness matrix.

time The current simulation time

neq The number of equations

1. When the restart flag is set, FEBio will create a dump file at the end of each converged time step. This dump file can then later be used to restart the analysis from the last converged time step. See Section Restarting a Run and Chapter 5 for more details on FEBio's restart feature.

2. The run command is used to start an FEBio task. This command takes the same options that you can enter on the command line. For example, to run a file named test.feb from the FEBio prompt, type the following:

run –i test.feb

1. The following configuration file settings can be set from the febio command prompt.

output_negative_jacobians turn on or off the detailed output when negative jacobians are encountered.

print_model_params turn on or off the output of the parameter values of parameters that are load controlled.

show_warnings_and_errors turn on or off the printing of warning and error messages.

To turn the option on (off), follow the set command by the variable name and then a value of 1 (0). For example,

set output_negative_jacobians 1

If you enter the set command without any additional options, a list will be printed of the current configuration settings.

1. The list command prints a list of all available FEBio features. Additional options can be specified to configure the output.

-m Specify the module name. (e.g. list -m solid)

-c Specify the category. (e.g. list -m FEMATERIAL_ID)

-n Set the max nr of lines in the output (e.g. list -n 100)

-s Specify a general pattern that should match. (e.g. list -s neo)

---

1. This feature does not work on some Linux platforms and may abruptly terminate the run. ↩