CAMP: Adding a Reaction Type

Note: these instructions are out-of-date. TODO update

Adding a reaction to the camp-chem module can be done in the following steps:

Step 1. Create a new reaction module

The module should be placed in the /src/rxns folder and extent the abstract camp_rxn_data::rxn_data_t type, overriding all deferred functions, and providing a constructor that returns a pointer to a newly allocated instance of the new type:

module rxn_foo
 
  use ...
 
  implicit none
  private
 
  public :: rxn_foo_t
 
  type, extends(rxn_data_t) :: rxn_foo_t
  contains
     ... (all deferred functions) ...
  end type rxn_foo_t
 
  ! Constructor
  interface rxn_foo_t
    procedure :: constructor
  end interface rxn_foo_t
 
contains
 
  function constructor() result(new_obj)
    type(rxn_foo_t), pointer :: new_obj
    allocate(new_obj)
  end function constructor
 
  ...
 
end module camp_rxn_foo

Step 2. Add the reaction to the camp_rxn_factory module

module camp_rxn_factory
 
 ...
 
 ! Use all reaction modules
 ...
 use camp_rxn_foo
 
 ...
 
 !> Identifiers for reaction types - used by binary packing/unpacking
 !! functions
 ...
 integer(kind=i_kind), parameter :: RXN_FOO = 32
 
 ...
 
 !> Create a new chemical reaction by type name
 function create(this, type_name) result (new_obj)
   ...
   select case (type_name)
     ...
     case ()
       new_obj => rxn_foo_t()
   ...
 end function create
 
 ...
 
 !> Pack the given value to the buffer, advancing position
 subroutine bin_pack(this, rxn, buffer, pos)
   ...
   select type (rxn)
     ...
     type is (rxn_foo_t)
       rxn_type = rxn_foo
   ...
 end subroutine bin_pack
 
 ...
 
 !> Unpack the given value to the buffer, advancing position
 function bin_unpack(this, buffer, pos) result (rxn)
   ...
   select case (rxn_type)
     ...
     case (rxn_foo)
       rxn => rxn_foo_t()
   ...
 end function bin_unpack
 
 ...
 
end module camp_rxn_factory

Step 4. Add the new module to the CMakeList file in the root directory.

...
 
# partmc library
 
set(REACTIONS
    ...
    src/rxns/camp_foo.F90
)
 
...

Step 5. Add unit tests for the new rxn_foo_t type

Unit testing should cover, at minimum, the initialization, time derivative and Jacbian matrix functions, and in general 80% code coverage is recommended. Some examples can be found in the /src/test folder.

Step 6. Update documentation

TODO finish...

Usage

The new reaction type is now ready to use. To include a reaction of this type in a mechanism, add a reaction object to a new or existing camp-chem configuration file as part of a mechanism object. The reaction should have a type corresponding to the newly created reaction type, along with any required parameters:

{  : [
  {
     : ,
     : ,
     : [
      {
         : ,
        ...
      },
      ...
    ]
  },
  ...
]}