US 6.3

16.2. Command Reference

The current section contains the detailed description of the directives and commands that can be used within NFIL files.

 

16.2.1. Directives

Directives are special commands that configure the way simulations are run, rather than the simulations themselves. In this sections, the different directives are described:

Directive: @version

Description: Specifies the version of the NFIL file format used. This directive is intended to be used for backwards-compatiblity reasons. At the moment, it should be passed the argument "1".

Example:

@version 1

 

Directive: @set_module

Description: Sets the module of the simulation. Currently, only US module simulations are supported.

Arguments: This directive only takes one argument: the name of the module that will be used.

Example:

@set_module us

 

Directive: @log

Description: Allows to configure the logging of messages during the simulation.

Arguments: The first argument can be "off" if the user does not need logging, "stdout" if the user wants to see the messages of the simulation in the standard output, or "file" if the user wants to output messages to a file. If the first argument is "file", the directive will accept an additional argument specifying the path to the output log file.

Examples:

@log off

@log stdout

@log file log.txt

 

Directive: @output_nfp

Description: Allows the creation of a NFP (newFASANT project) file containing the generated simulation. This NFP can later be opened with the newFASANT GUI. This functionality is intented to be used with debugging or troubleshooting purposes, as the generation of the NFP project file takes some time.

Arguments: This directive only takes one argument: either "off" if the user wants to disable this functionality (although it is disabled by default) or the path to the resulting NFP file.

Examples:

@output_nfp off

@output_nfp project.nfp

 

16.2.2. Commands

In this section, the available commands available for US simulations are documented. Please note that all paths are relative to the folder where the NFIL file is located.

Command: add_geom

Description: Adds the geometry from a NUR file to the simulation.

Arguments: The add_geom commands accepts two arguments:

  • The path to the NUR file with the geometry to be added to the simulation.
  • The path to the MAT file that defines the affine transformation applied to the geometry.

Example:

add_geom car.nur car.mat

 

Command: add_sound_source

Description: Adds a new ultrasound source to the simulation.

Arguments: This command accepts the following arguments, in order:

  • The path to the MAT file that defines the affine transformation applied to the source.
  • The amplitude of the ultrasound source.
  • The phase of the ultrasound source.
  • The frequency of operation of the DUS file given in the next argument, in KHz.
  • The DUS file that the defines the ultrasound pattern.

The later two arguments can be repeated if the user wants to specify DUS pattern files for different frequencies.

Examples:

add_sound_source source.mat 1.0 0.0 50.0 pattern.dus

add_sound_source source.mat 1.0 0.0 50.0 pattern50khz.dus 60.0 pattern60khz.dus

 

Command: set_simulation_type

Description: Sets the simulation type of the current US simulation. Note that some other commands will only work when the simulation is of a certain type.

Arguments: This command only takes one argument: the simulation type. The simulation type can either be "near" for Near Field simulations, "coupling" for coupling simulations or "doppler" for doppler simulations.

Examples:

set_simulation_type near

set_simulation_type coupling

 

Command: set_frequency

Description: Sets the frequency of the simulation.

Arguments: This command only takes one argument: the frequency in KHz.

Example:

set_frequency 50.0

 

Command: set_freq_sweep

Description: Sets a frequency sweep for the simulation.

Precondition: The simulation type must not be Doppler.

Arguments: This command takes the following arguments, in order:

  • The initial frequency of the simulation, in KHz.
  • The final frequency of the simulation, in KHz.
  • The number of frequency samples in the interval of frequencies.

Example:

set_freq_sweep 50.0 60.0 3

 

Command: set_speed_sound

Description: Sets the speed of sound of the simulation.

Arguments: This command only takes one argument: the speed of sound in m/s.

Example:

set_speed_sound 340.0

 

Command: set_speed_sweep

Description: Sets a sweep of speeds of sound for the simulation.

Precondition: The simulation type must not be Doppler.

Arguments: This command takes the following arguments, in order:

  • The initial speed of sound, in m/s.
  • The final speed of sound, in m/s.
  • The number of samples in the interval of speeds.

Example:

set_speed_sweep 340.0 350.0 3

 

Command: set_bounces

Description: Sets the number of effects per ray that will be calculated in the ray-tracing.

Arguments: This command only takes one argument: the number of desired effects.

Example:

set_bounces 2

 

Command: set_effects

Description: Sets the types of effects that will be taken into account when calculating rays in the ray-tracing. Note that direct and reflected rays are ALWAYS calculated.

Arguments: This command takes the list of effects to be calculated, or "none" if the user does not want to calculate any effects other than direct and reflected. The available effects are "Tx" (transmission) and "Rf" (refraction).

Examples:

set_effects Tx Df

set_effects none

 

Command: add_passive

Description: Adds a new receiver to the simulation.

Precondition: Simulation must be of type Coupling.

Arguments: This command takes the following arguments:

  • Path to the MAT file that defines the position and orientation of the receiver.
  • Path to the DUS file that defines the ultrasound pattern of the receiver.
  • The efective area of the receiver, in m2.

Example:

add_passive passive.mat passive.dus 0.01

 

Command: set_doppler_freq_bin

Description: Sets the Doppler frequency bin value.

Precondition: Simulation must be of type Doppler.

Arguments: This command takes only one argument: the Doppler frequency bin, in Hz.

Example:

set_doppler_freq_bin 1.0

 

Command: set_doppler_velocity_obj

Description: Sets the doppler velocity for a geometry object.

Precondition: Simulation must be of type Doppler.

Arguments: This command takes the following arguments:

  • The name of the object. The name of an object is the name set to it before exporting to NUR.
  • The three components (X, Y, Z) of the vector that defines the velocity, in m/s.

Example:

set_doppler_velocity_obj car 26.0 0.0 0.0

 

Command: set_doppler_rotation_obj

Description: Sets the doppler rotation for a geometry object.

Precondition: Simulation must be of type Doppler.

Arguments: This command takes the following arguments:

  • The name of the object. The name of an object is the name set to it before exporting to NUR.
  • The three components (X, Y, Z) of the first point of the rotation axis.
  • The three components (X, Y, Z) of the second point of the rotation axis.
  • The rotation speed, in rad/s.

Example:

set_doppler_rotation_obj box 0.0 0.0 0.0 0.0 0.0 1.0 0.5

 

Command: set_doppler_velocity_source

Description: Sets the doppler velocity for an ultrasound source.

Precondition: Simulation must be of type Doppler.

Arguments: This command takes the following arguments:

  • The index (starting at 1) of the source the user wants to apply the velocity to. Indices are assigned sequentially to sources when they are created with the add_sound_source command.
  • The three components (X, Y, Z) of the vector that defines the velocity, in m/s.

Example:

set_doppler_velocity_source 1 1.0 2.0 0.0

 

Command: set_doppler_velocity_obs

Description: Sets the doppler velocity for an observation point group.

Precondition: Simulation must be of type Doppler.

Arguments: This command takes the following arguments:

  • The index (starting at 1) of the observation point group the user wants to apply the velocity to. Indices are assigned sequentially to observation point groups when they are created.
  • The three components (X, Y, Z) of the vector that defines the velocity, in m/s.

Example:

set_doppler_velocity_obs 1 1.0 2.0 0.0

 

Command: set_meshing_processors

Description: Sets the number of processors that will be used for meshing.

Arguments: This command only takes one argument: the number of processors that will be used.

Example:

set_meshing_processors 4

 

Command: set_executing_processors

Description: Sets the number of processors that will be used for execution.

Arguments: This command only takes one argument: the number of processors that will be used.

Example:

set_executing_processors 4

 

Command: set_processors

Description: Sets the number of processors that will be used for meshing and execution. This command is a shortcut for setting the number of processors for both calculations without the need to call two commands.

Arguments: This command only takes one argument: the number of processors that will be used.

Example:

set_processors 4

 

Command: add_point_observation

Description: Adds an observation point to the simulation.

Precondition: Simulation type must not be Coupling.

Arguments: This command takes the following arguments:

  • Path to the DIS file that defines the translation applied to this observation point.
  • Coordinates (X, Y, Z) of the point. The result of applying the translation defined in the DIS file to this point will be the location of the observation point.

Example:

add_point_observation obs1.dis 2.0 1.0 0.0

 

Command: add_cylinder_observation

Description: Adds a cylinder (or cylindrical section) of observation points to the simulation.

Precondition: Simulation type must not be Coupling.

Arguments: This command takes the following arguments (all distances are expressed in meters):

  • Path to the DIS file that defines the translation applied to this group of observation points.
  • The coordinates (X, Y, Z) of the center of the cylinder's base.
  • The radius of the cylinder.
  • The number of points along the height of the cylinder.
  • The height of the cylinder.
  • The number of points along the circumference of the cylinder.
  • The initial angle of the cylindrical section, in degrees.
  • The final angle of the cylindrical section, in degrees.

Example:

add_cylinder_observation obs2.dis 0.0 0.0 0.0 2.0 11 20.0 10 0.0 180.0

 

Command: add_line_observation

Description: Adds a line of observation points.

Precondition: Simulation type must not be Coupling.

Arguments: This command takes the following arguments (all distances are given in meters):

  • The path to a MAT or DIS file defining an affine transformation or a translation, respectively.
  • The number of points of the line.
  • The coordinates (X, Y, Z) of the initial point of the line.
  • The coordinates (X, Y, Z) of the final point of the line.

Examples:

add_line_observation obs3.dis 21 10.0 0.0 0.0 20.0 0.0 0.0

add_line_observation obs3.mat 11 0.0 0.0 0.0 0.0 10.0 0.0

 

Command: add_parallelogram_observation

Description: Adds a parallelogram of observation points.

Precondition: Simulation type must not be Coupling.

Arguments: The command takes the following arguments (all distances are given in meters):

  • The path to a MAT or DIS file defining an affine transformation or a translation, respectively.
  • The coordinates (X, Y, Z) of three points defining the vertices of the parallelogram. The fourth point is calculated by using the other three points.
  • The number of points along the direction from the first to the second point.
  • The number of points along the direction from the second to the third point.

Example:

add_parallelogram_observation obs4.mat 2.0 2.0 0.0 0.0 0.0 0.0 4.0 0.0 0.0 11 11

 

Command: add_plane_observation

Description: Adds a plane of observation points to the simulation.

Precondition: Simulation type must not be Coupling.

Arguments: The command takes the following arguments (all distances are given in meters):

  • The path to a DIS path defining the translation applied to this group of observation points.
  • The constant coordinate of the plane (can either be "x", "y" or "z").
  • The value of the constant coordinate of the plane.
  • The initial value of the first non-constant coordinate of the plane.
  • The total size of the plane along its first non-constant coordinate.
  • The number of points along the first non-constant coordinate of the plane.
  • The initial value of the second non-constant coordinate of the plane.
  • The total size of the plane along its second non-constant coordinate.
  • The number of points along the second non-constant coordinate of the plane.

Example:

add_plane_observation obs5.dis y 2.0 1.0 5.0 5 2.0 6.0 5

 

Command: add_sphere_observation

Description: Adds a sphere of observation points to the simulation.

Precondition: The simulation type must not be Coupling.

Arguments: The command takes the following arguments (all distances are given in meters):

  • The path to the DIS file with the translation applied to this group of observation points.
  • The coordinates (X, Y, Z) of the center of the sphere.
  • The initial radius of the sphere.
  • The increment between two consecutive radius values.
  • The number of radius values.
  • The number of points along the theta direction.
  • The initial theta value, in degrees.
  • The final theta value, in degrees.
  • The number of points along the phi direction.
  • The initial phi value, in degrees.
  • The final phi value, in degrees.

Example:

add_sphere_observation obs6.dis 2.0 0.0 0.0 10.0 1.0 3 11 0.0 90.0 21 0.0 180.0

 

We use cookies on this website to improve your navigation experience on this site. By using this site, you agree to our cookie policy.

I agree