# Input File

To access a user-defined function in AcuTrace, you must reference it in the input file.

For example, to access the user-defined function usrEner(), a user equation needs to be defined and then added to the list of user equations. To define the user equation energy, the following command may be specified in the input file:
USER_EQUATION( "energy" ) {
num_variables = 1
user_values   = {5.0, 0.015}
user_string   = {"test"}
type          = evolve
}

This user equation command defines a user equation with one component governed by an evolution equation. The right hand side of the evolution equation is found by evaluating usrEner. Note that the value of the user_function parameter is exactly the name of the function (routine) used in the C program written by you. The parameters user_values and user_strings are used to pass parameters to the user function. In this example, two floating-point numbers and one string are passed to the function. The order of these parameters is preserved, for example the first user value is 5.0 and the second is 0.015.

The user equations defined in USER_EQUATION commands can be added to the list of user equations in the EQUATION command. For example,
particle       = massless
user_equations = {energy}
}
A user equation that has been defined and added to the list of user equations is part of the particle solution field. If a user equation is defined but not referenced in the EQUATION command, it is not part of the particle solution field and has no effect. The initial values of the user equation come from one or more USER_EQUATION_INITIAL_CONDITION commands, for example,
USER_EQUATION_INITIAL_CONDITION (energy) {
particle_seed   = seeds
user_equation   = energy
type            = constant
constant_values = { 10.0 }
}

Note that the value of the user_equation parameter in the USER_EQUATION_INITIAL_CONDITION command is the qualifier used in the USER_EQUATION command, not the name of the C function.

A user equation in the list of user equations in the EQUATION command will automatically be advanced if the AUTO_SOLUTION_STRATEGY is used, for example,
AUTO_SOLUTION_STRATEGY {
max_time     = 0.0
max_segments = 10000
}
Otherwise, the user equation is advanced only if the user equation is referenced in a STAGGER command that is in turn referenced by the TIME_SEQUENCE command, for example,
TIME_SEQUENCE {
...
staggers = {particle, energy}
...
}
STAGGER(energy) {
equation      = user_equation
user_equation = energy
}

If the user equation is not so referenced, it simply retains its initial values throughout the analysis. See the AcuTrace Command Reference Manual for more details on the inputs for user-defined functions.