USER_EQUATION_INITIAL_CONDITION

Specifies the initial user equation values for a particle set and a single user equation.

Type

AcuTrace Command

Syntax

USER_EQUATION_INITIAL_CONDITION ("name") {parameters...}

Qualifier

User-given name.

Parameters

particle_seed or seed (string) [no default]

The name of the particle set. Must be a qualifier used in one of the PARTICLE_SEED commands.

user_equation (string) [no default]

The name of the user equation. Must be a qualifier used in one of the USER_EQUATION commands.

type (enumerated) [=constant]

The type of initial condition specification.

constant: Assign the same initial condition to all seeds.
per_seed: Use a list of initial conditions.
random: Randomly assign initial condition.

constant_values (array) [no default]

User equation initial condition assigned to all seeds. The size of the array must equal the number of variables in the user equation. Use only if type is constant.

seed_values (array) [no default]

List of initial condition vectors, one per seed. The number of columns in each row must the number of variables in the user equation. The number of rows must equal the number of seeds in the seed group. Use only if type is per_seed.

random_bounds (array) [no default]

Upper and lower bounds used to assign the random initial conditions. The array should have two rows, one for each bound. The number of columns in each row equal must the number of variables in the user equation. Use only if type is random.

Description

Initial conditions must be assigned for every user equation that appears in the user_equations parameter of the EQUATION command. The initial conditions for each such equation are assigned per seed set. The USER_EQUATION_INITIAL_CONDITION command sets the initial conditions for the pairing of a single user equation with a single particle seed set. Every pairing of a user equation appearing in the user_equations parameter and a particle seed set must have an associated USER_EQUATION_INITIAL_CONDITION command. For example, if there are two user equations, user1 and user2, and three seed sets, seed1, seed2, and seed3, for example,

EQUATION {
   ...
   user_equations = {user1, user2}
}
PARTICLE_SEED( "seed1" ) {
   ...
}
PARTICLE_SEED( "seed2" ) {
   ...
}
PARTICLE_SEED( "seed3" ) {
   ...
}

there must be six USER_EQUATION_INITIAL_CONDITION commands:

USER_EQUATION_INITIAL_CONDITION( "seed1_user1" ) {
   particle_seed = "seed1"
   user_equation = "user1"
   ...
}
USER_EQUATION_INITIAL_CONDITION( "seed1_user2" ) {
   particle_seed = "seed1"
   user_equation = "user2"
   ...
}
USER_EQUATION_INITIAL_CONDITION( "seed2_user1" ) {
   particle_seed = "seed2"
   user_equation = "user1"
   ...
}
USER_EQUATION_INITIAL_CONDITION( "seed2_user2" ) {
   particle_seed = "seed2"
   user_equation = "user2"
   ...
}
USER_EQUATION_INITIAL_CONDITION( "seed3_user1" ) {
   particle_seed = "seed3"
   user_equation = "user1"
   ...
}
USER_EQUATION_INITIAL_CONDITION( "seed3_user2" ) {
   particle_seed = "seed3"
   user_equation = "user2"
   ...
}

The user given names, seed1_user1, and so on, do not need to follow the convention used in this example, as long as each seed set and user equation pairing is assigned a unique name.

Initial conditions can be assigned in one of three ways. To illustrate, assume seed set seed1 has three seeds and user function user1 has four variables:

a constant over the seed set, for example,

USER_EQUATION_INITIAL_CONDITION( "seed1_user1" ) {
   particle_seed   = "seed1"
   user_equation   = "user1"
   type            = constant
   constant_values = { 1.0, 2.0, 3.0, 4.0 }
}

per seed, for example,

USER_EQUATION_INITIAL_CONDITION( "seed1_user1" ) {
   particle_seed = "seed1"
   user_equation = "user1"
   type          = per_seed
   constant_values  = {    1.0, 2.0, 3.0, 4.0 ;
                        1.1, 2.3, 2.9, 3.7 ;
                        1.2, 2.4, 3.1, 4.2
                   }
}

randomly, for example,

USER_EQUATION_INITIAL_CONDITION( "seed1_user1" ) {
   particle_seed = "seed1"
   user_equation = "user1"
   type          = random
   random_bounds = {    1.0, 1.9, 2.8, 3.5 ;
                        2.0, 3.5, 4.1, 4.7
                   }
}

When type equals per_seed, the number of initial value vectors, three in the example shown, must equal the number of seeds in the seed set. When type equals random, each component of each user equation value is randomly assigned a value between the corresponding bounds. Here, the first components all lie between 1.0 and 2.0, the second between 1.9 and 3.5, and so on.

A USER_EQUATION_INITIAL_CONDITION command is allowed but not required for pairings of particle seed groups with user equations that do not appear in the user_equations parameter of the EQUATION command. For example, in the following:

EQUATION {
   ...
   user_equations = {user1}
}
PARTICLE_SEED( "seed1" ) {
   ...
}
USER_EQUATION( "user1" ) {
   ...
}
USER_EQUATION( "user2" ) {
   ...
}

the command

USER_EQUATION_INITIAL_CONDITION( "seed1_user2" ) {
   particle_seed = "seed1"
   user_equation = "user2"
   ...
}

allowed but not required. In fact, since user2 is not listed by the user_equations parameter, the command USER_EQUATION_INITIAL_CONDITION("seed1_user2") command has no effect.

A pairing of a seed set and a user equation can only appear in one USER_EQUATION_INITIAL_CONDITION command. If the same pairing of seed set and user equation appears in more than one USER_EQUATION_INITIAL_CONDITION command, an error will be reported, for example, if the following two commands are used:

USER_EQUATION_INITIAL_CONDITION( "seed1_user2_a" ) {
   particle_seed = "seed1"
   user_equation = "user2"
   ...
}
USER_EQUATION_INITIAL_CONDITION( "seed1_user2_b" ) {
   particle_seed = "seed1"
   user_equation = "user2" 
   ...
}