Warning

This documentation will no longer be mantained. The official FARGO3D repository is now https://github.com/FARGO3D/fargo3d, and the documentation is https://fargo3d.github.io/documentation/

.opt files

FARGO3D is a very versatile code. It can solve from a very simple sod shock tube test to a tridimensional problem with MHD. In order to keep the versatility without a performance penalty, we have adopted an extensive use of macrocommand variables. These variables allow one to activate/deactivate a lot of sections of the code depending on what we want to solve. For example, if we want to solve a 2D planetary disk without MHD, the code does not need to know anything about MHD. In this case, an “if run time sentence checking whether we want to use MHD or not, would be expensive. With the help of this compiler variables through #ifdef statements, all the job is done at compilation time.

Most of these variables are defined in the .opt file, but there are other ones (for example FARGO_DISPLAY), that are defined during the Make Process.

The variables must be defined inside a container variable, called FARGO_OPT, as follows

FARGO_OPT += -DVARIABLE.

In this version, the list of options/modules that can be activated from the .opt file is:

Fluids

These options are mandatory (see Multifluid)

  • FLUIDS := 0 1 2 (list starting from 0,…,N-1, with N the number of fluids)

  • NFLUIDS = 3 (total number of fluids)

  • FARGO_OPT += -DNFLUIDS=${NFLUIDS} (mandatory line in the .opt file)

  • DRAGFORCE: Activates the drag force between fluids.

  • STOKESNUMBER: The collision rate is computed assuming fluids with constant Stokes Number (in linear regime).

Performance:

  • FLOAT: Uses single precision floating point data. On GPUs, the code runs ~2x times faster. If FLOAT is not defined, the code will be run in double precision.

Dimensions:

  • X: Activates the X direction.

  • Y: Activates the Y direction.

  • Z: Activates the Y direction.

Note: Some fields are not available until one specific direction is activated.

Equation of state:

  • ADIABATIC: The equation of state \(P=(\gamma-1)e\) will be used. The field Energy is the volumic internal energy \(e\).

  • ISOTHERMAL: The equation of state \(P=cs^2\rho\) will be used. The (ill-named) field Energy is then the sound speed of the fluid.

Additional Physics:

  • MHD: Activates the MHD solver. The options X, Y & Z must be all activated. The options below are enabled for MHD runs.

    • STRICTSYM: It enforces a strict symmetry of the MHD solver.

    • OHMICDIFFUSION: Activates Ohmic resistivity.

    • AMBIPOLARDIFFUSION: Activates ambipolar diffusion.

    • HALLEFFECT: Activates the Hall effect.

  • VISCOSITY: Activates the viscosity module with a constant kinematic viscosity defined by the parameter NU.

  • ALPHAVISCOSITY: Activates the viscosity module with a constant alpha viscosity defined by the parameter ALPHA (Shakura-Sunyaev (1973) Viscosity Prescription).

  • POTENTIAL: Activates the gravity module.

  • STOCKHOLM: Activates wave killing boundary conditions in Y & Z. Very useful for local studies where reflections on the edges must be avoided.

  • HILLCUT: Activates a cut for the force computation. Must to be defined in order to accept ExcludeHill parameter file variable set to yes.

Coordinates:

  • CARTESIAN: x,y,z are Cartesian.

  • CYLINDRICAL: x –> azimuthal angle, y –> cylindrical radius, z –> z.

  • SPHERICAL: x –> azimuthal angle, y –> spherical radius, z –> colatitude.

Transport:

  • RAM: Enables the Rapid Advection Algorithm on Arbitrary Meshes (Benítez-Llambay et al. 2023). RAM is a time-explicit method to solve the advection equation in problems with large bulk velocity, allowing to increase the time step significantly on both uniform and non-uniform domains.

  • STANDARD: Forces the standard advection algorithm in x. By default, the x-advection is done with the orbital advection (FARGO) algorithm.

Slopes:

  • DONOR: Activates the donor cell flux limiter for the transport. Actually, deactivates the default van Leer’s second order upwind interpolation.

Artificial Viscosity:

  • NOSUBSTEP2: If it not defined, the artificial viscosity module, called Substep2(), is invoked.

  • STRONG_SHOCK: If strong shocks make the code crash, you may try using this variable. It is never used in the tests. It uses a linear, rather than quadratic, artificial pressure.

Boundaries

Cuda blocks:

The cuda blocks must be defined in the form:

ifeq (${GPU}, 1)
FARGO_OPT += -DBLOCK_X=16
FARGO_OPT += -DBLOCK_Y=8
FARGO_OPT += -DBLOCK_Z=4
endif

This is needed to define a default block size for GPU kernels. Alternatively, for a given platform, you may determine individually for each CUDA kernel (“routine”) which block size gives best results.

See also

Improving CUDA Performance

There is a special set of variables not contained in the FARGO_OPT variable:

MONITOR_2D
MONITOR_Y
MONITOR_Y_RAW
MONITOR_Z
MONITOR_Z_RAW
MONITOR_SCALAR

Those are used at build time to request systematic, fine grain monitoring. The meaning of these variables is explained in Monitoring.