3-NIRVANA-user-guide/3.2-User-interfaces.md

-![logo_short_small](uploads/1e4ee858ca174663b210647640da0976/logo_short_small.png) `4`
+![logo_short_small](uploads/1e4ee858ca174663b210647640da0976/logo_short_small.png) `4.1`
 
 CONTENTS:    
 [Overview](3.2-User-interfaces#overview)  
@@ -11,6 +11,7 @@ CONTENTS:
 [User-defined cooling and heating function](3.2-User-interfaces#user-defined-cooling-and-heating-function)  
 [User-defined equation of state](3.2-User-interfaces#user-defined-equation-of-state)  
 [User-defined mesh refinement](3.2-User-interfaces#user-defined-mesh-refinement)  
+[User-defined background magnetic field](3.2-User-interfaces#user-defined-background-magnetic-field)
 [Specification of NCCM parameters](3.2-User-interfaces#specification-of-nccm-parameters)  
 [User-controllable macros](3.2-User-interfaces#user-controllable-macros)
 
@@ -46,6 +47,9 @@ recognized by C files ending on `User.c`:
 -   `initDomainUser.c`,`checkDomainUser.c` – user-defined initial- and
     restricted mesh refinement
 
+-   `sourceB0User.c` - user-defined background magnetic field in the 
+    B-splitting formalism
+
 Defining interfaces requires some familiarity with NIRVANA and, in
 particular, a basic understanding of its data structure. The defintion
 of IC in `configUser.c` is the minimum necessary for a problem setup.
@@ -839,6 +843,12 @@ infrastructure is used testfield fluctuation variables,
 **b**<sub>*t*</sub>, *t*=0,*N*<sub>*t*</sub>−1, are to be
 considered primary.
 
+*Note: In case magnetic field splitting is enabled
+(cf. [Functionality overview](3.1-Code-basics#functionality-overview))
+the variable **B** represents the residual magnetic field which
+must be initialized instead of the total field. Likewise, *e* represents
+the residual total energy density.*
+
 The mesh is represented by the master mesh pointer `gm` which is the
 only argument passed to function `configUser()`. The problem-relevant
 variables have to be assigned for each superblock `g` in `gm`. Recall
@@ -1834,6 +1844,36 @@ the requested refinement control parameter.
 An example can be found in the testproblem
 `/nirvana/testproblems/GRAVITY/problem3`.
 
+## User-defined background magnetic field
+
+The module `sourceB0User.c` serves as template
+for coding a background magnetic field, **B**<sup>0</sub>, in the context
+of the magnetic field splitting formalism.
+**B**<sup>0</sup> must be a time-independent, divergence-free potential field, i.e.,
+
+$\partial_t$**B**<sup>0</sub>=0,
+
+∇⋅**B**<sup>0</sup>=0
+
+∇×**B**<sup>0</sup>=0.
+
+In the call of `sourceB0User()`
+the function arguments are the pointer to the array `B0` of magnetic field
+components and the coordinates `x,y,z`:
+
+      sourceB0User(B0,x,y,z);
+
+The user must define the components
+`B0[0], B0[1]` and `B0[2]` in the x-,y- and z-direction, respectively,
+as a function of (x,y,z).
+
+An example definition for a background field (magnetic dipole) can be found in
+testproblem `/nirvana/testproblems/MHD/problem30`.
+
+The B-splitting scheme is enabled
+by setting the macro `B_FIELD_SPLITTING=YES` in the user interface
+[nirvanaUser.h](3.2-User-interfaces#user-controllable-macros).
+
 ## Specification of NCCM parameters
 
 The parameter file `NCCM.par` serves as user interface to the
@@ -2098,4 +2138,4 @@ values (given in brackets).
 
 &nbsp;
 
-PREV: [3.1 Code basics](3.1-Code-basics) &nbsp; &nbsp; &nbsp; NEXT: [3.3 Output data](3.3-Output-data)
+PREV: [3.1 Code basics](3.1-Code-basics) &nbsp; &nbsp; &nbsp; NEXT: [3.3 Output data](3.3-Output-data)
\ No newline at end of file