Input Decks

VPIC input decks are arbitrary C++ code, that get compiled into the simulation during the second pass of a 2-stage compile. This means they are very powerful, but great care must be taken.

Structure

The decks are comprised of different sections, each of which is documented below. A great first deck to read for some examples and documentation is the sample harris deck.

Initialization (begin_initialization)

The code inside the begin_initialization block is called before the main simulation loop, and is used to set-up the desired simulation. The following is true when the initialization is called:

• MPI has been initialized
• The random number generated has been seeded (based on unique rank)
• There is a blank grid created for the user

The user is then expected to:

• Define the contents of the grid (define_periodic_grid())
• Define units and timestep (define_units(), define_timestep())
• Define the materials and particle species. (define_material())
• Load the initial field (define_field_array(), set_region_field())
• Insert the default particle populations (inject_particle())
• Set domain boundary conditions (set_domain_field_bc, set_domain_particle_bc)
• Set simulation specific variables, such as num_step.

Upon completion of the initialization, the following occurs:

• The synchronization error (tang E, norm B) is computed between domains and tang E / norm B are synchronized by averaging where discrepancies are encountered.
• The initial divergence error of the magnetic field is computed and one pass of cleaning is done (for good measure)
• The bound charge density necessary to give the simulation an initially clean divergence e is computed.
• The particle momentum is uncentered from u_0 to u_{-1/2}
• The user diagnostics are called on the initial state
• The physics loop is started

Diagnostics (begin_diagnostics)

This is the chance for users to add custom code which may run at the end of every simulation step. Common tasks include dumping data to disk for offline analysis (dump_particles, dump_fields, dump_hydro), invoking checkpointing or performing custom analysis or computation. Many users draft initial code functionality here, which can then be integrated into the main code for us by all.

Globals (begin_globals)

Globals give the user to have custom variables that can be used throughout the input deck, and are preserved across restarts. Variables are typically set during user initialization, but can be set anywhere as appropriate.

The code currently stores these globals using type-punning, up to a size of USER_GLOBAL_SIZE (currently 16k bytes). Storing more than this in very unlikely, but could cause unexpected behavior.

Custom Particle Injection (begin_particle_injection)

Particle injection allows the user to add new particles during a time-step, after the particle advance, but before the field solve. This is useful to do something like simulation a particle beam that continues throughout the simulation.

Custom Current Injection (begin_current_injection)

Allows the user to inject current after jf is synchronized and before the fields are advanced. At this point, the particle currents are known at jf_{1/2} and it is the users responsibility to insure injected currents are consistent across domains.

If the user wants to inject current and retain the ability to correct clean the field divergence, then the user must also update rhob according to rhob_1 = rhob_0 + div juser_{1/2}

Custom Field Injection (begin_field_injection)

Allows the user to inject custom fields after the fields have been advanced, where E is at t=1 and B is at t=1/2

Custom Particle Collisions (begin_particle_collisions)

WARNING: Users looking to do collisions should first see if the inbuilt collision operator can meet their needs, this section of the input deck is only for custom collisions (which are applied after the in-built collisions).

Users can apply a custom iterate over particle species to manually perform collisions after the sort and before the particle advance

Special Variables

As the input deck is part of the vpic_simulation class, it has access to both read and write variables inside the class, as well as call any functions. As such, there are a few "special" variables a user is expected/able to set.

These can be broken into two sections, the first where the code will actively read the values set:

  int verbose;              // Should system print some useful additional information                            
  int num_step;             // Number of steps to take                             
  int num_comm_round;       // Num comm round                                      
  int status_interval;      // How often to print status messages                  
  int clean_div_e_interval; // How often to clean div e                            
  int num_div_e_round;      // How many clean div e rounds per div e interval   
  int clean_div_b_interval; // How often to clean div b                            
  int num_div_b_round;      // How many clean div b rounds per div b interval   
  int sync_shared_interval; // How often to synchronize shared faces   

The second as convenience functions for users, which do nothing unless explicitly used in the input deck. These values however can be modified between restarts, using the modify flag.

  double quota;                                                                    
  int checkpt_interval;                                                            
  int hydro_interval;                                                              
  int field_interval;                                                              
  int particle_interval;          

Checkpointing

VPIC can fully checkpoint and restore, but only does so if the user instructs it to using the input deck (even if the above checkpt_interval is set, a user still has to process that manually). One can do this by calling checkpt() with a desired filename and an optional tag.

How deck parsing and compiling works

Each of the above functions (begin_xxx) is really a C pre-processor macro which expands to be a named member function of the vpic_simulation class (see .deck/wrapper.h). When the input deck is compiled against the core vpic library, the code inside the input deck is inserted as the body of those member functions. If for example you wanted to see when and where in the code begin_initialization is called, you must first determine that it really aliases vpic_simulation::user_initialization, and instead see where that is used.