Simulation Workflow

When using newFASANT in closed-loop mode, the user needs to provide a path to a NFIL file that contains the specification of the simulation case. This file consists of a series of directives and commands that are used for setting up the simulation case (i.e simulation parameters, geometry, sources and observation points). An example of NFIL file is provided below:

@version 1
@log stdout
@set_module us
set_simulation_type doppler
# Geometry.
add_geom box.nur box.mat
# Sources.
add_sound_source source.mat 1.0 0.0 50.0 unit.dus
# Simulation parameters.
set_frequency 50.0
#set_freq_sweep 50.0 60.0 3
set_speed_sound 340.0
set_bounces 1
set_effects Df Tx
# Observations.
add_point_observation obs.dis 0.0 0.0 0.0
# Doppler.
set_doppler_freq_bin 1.0
set_doppler_velocity_obj box 1.0 0.0 0.0
set_doppler_velocity_source 1 -1.0 0.0 0.0
set_doppler_velocity_obs 1 2.0 0.0 0.0
# Calculation.
set_processors 4

NFIL files are processed line by line. Empty lines and lines starting with the "#" character (comments) are ignored by the parser. Every other line consists in the name of a command followed by zero or more arguments, the number of which depends on the specific command or directive. Commands whose name begins with "@" are called directives, and the purpose of this type of commands is to configure details relating to how the closed-loop simulation is run rather than the simulation itself. As such, directives MUST always appear at the start of the file, and therefore no regular command can appear before any directive. Any file that does not comply with this rule will be considered invalid.

NFIL files are designed to be written only once even if multiple simulations are run within the same closed-loop simulation workflow. That happens because NFIL files only encode "static" information about the simulation geometry, observation points, sources, receivers and simulation parameters. The parameters of the simulation that are subject to change between simulations, such as the position and rotation of geometry, observation points and sources, are factored out into files other that the NFIL files DIS files and MAT files, which are the ones that are supposed to be modified by the external tool between simulations (usually in response to the results of the previous simulation). DIS files only encode information about the translation of a particular object, while MAT files encode translation, rotation and/or scaling by specifying an affine transformation matrix. Depending on the command, it will accept either a DIS file or a MAT file. Please check the "Command Reference" section for more details.

An example of the contents of a DIS file would be the following. This file encodes a translation of two meters along the X axis:

2.0 0.0 0.0

On the other hand, an example of the contents of a MAT file is presented below. This file represents a scaling along the X axis (by a factor of 2, as defined by the top-left 3x3 submatrix) and a translation of 3 units along both the X axis and the Y axis (as defined by the last column of the matrix):

2.0 0.0 0.0 3.0
0.0 1.0 0.0 3.0
0.0 0.0 1.0 0.0
0.0 0.0 0.0 1.0

The geometry for the simulation case provided to the add_geom command must be in newFASANT's NUR file format. Therefore, the user needs to use newFASANT GUI to design and export the geometry as a NUR file in order to be used in a closed-loop simulation workflow. The NUR file contains the information of the materials assigned to each surface of the geometry, so these do not need to be configured in the NFIL file.

After the NFIL file and all companion (NUR, DIS and MAT) files have been created, the user can run newFASANT in closed-loop mode by running the following command (using the command-line):

C:\newFASANT\newFASANT6.exe "C:\PathToNfil\spec.nfil"

The above command assumes that the installation directory of newFASANT is "C:\newFASANT" and that "C:\PathToNfil\spec.nfil" is the path where the NFIL file is located. Please note that all relative paths referenced from the NFIL file will be relative to the folder where the NFIL is located (in the previous example, that would be the "C:\PathToNfil" directory). This encourages a folder structure where all the files relating to the closed-loop simulation are located in the same directory.

When the above command is run, newFASANT will parse the NFIL file and build the simulation using the commands specified in this file. After the file is parsed, newFASANT will run the meshing and calculation process one after another. After the simulation is run, newFASANT will output the result files in the "mesh" and "result" folders inside the NFIL file folder.

To sum up, the following process should be followed when running a closed-loop simulation with newFASANT:

  • Create an empty folder that will contain the files used in the simulation.
  • Design and export as NUR the geometry to be used in the simulation. It is advisable to export each different object in the simulation as a separate NUR file so that these different objects can be transformed independently between simulations. These NUR files should be saved to the folder created in the previous step.
  • Create the NFIL file that will be the specification of the simulation. Check the "Command Reference" section for detailed information about the available commands for use in NFIL files.
  • The previous NFIL file will contain references to DIS and MAT files. Create these files with the translations and transformations desired for each of the objects, sources and observation points they refer to in the NFIL file.
  • Add the additional files referred to by the NFIL file, such as DUS files, to the NFIL folder.
  • Using the command-line, call the newFASANT6.exe executable with the path to the NFIL file.
  • Inspect the result files in the "mesh/" and "result/" folders inside the NFIL folder and, if desired, modify the DIS and MAT files and re-run the simulation. Repeat this step as many times as needed.