Improved reactions interface

[schmoelder]

Fixes #67

Changes:

• Bulk reaction model is always read from REACTION_MODEL_BULK (previously always REACTION_MODEL)
• Bulk reaction parameters are always read from reaction_bulk (previously mostly reaction_bulk, sometimes reaction)

The old version led to a lot of user errors; the newer version is more in more consistent and in in line with the particle reactions interface:

• Particle reaction model is always read from REACTION_MODEL_PARTICLES
• Particle reaction parameters are always read from reaction_particle

It does introduce some breaking changes in the interface but since reactions are quite new, there probably are actually very few people who use them. We could still read from the old location and throw a DeprecationWarning or, even better, this might also be a good opportunity to think again about how to realize #18.

---

Open question: Ambiguity in parameter naming

The proposed change still leaves some ambiguity in the naming of the parameters within the parameters branch.

From a discussion in the CADET Forum:

Internally, CADET has some functions to handle a cell in a particle (i.e., radial shell consisting of liquid and solid phase). This function is also used for the lumped rate model without pores (the bulk volume cells also consist of liquid and solid phase).
Hence, you’ll have to use the interface for reactions in particles

Thus, even though, we're defining a bulk reaction, we have to use the suffix _liquid for bulk reactions in that particular unit instead of _bulk:

cadet.root.input.model.unit_001.reaction_model_bulk = 'MASS_ACTION_LAW'
cadet.root.input.model.unit_001.reaction_bulk.mal_kfwd_liquid = kfwd
cadet.root.input.model.unit_001.reaction_bulk.mal_kbwd_liquid = kbwd
cadet.root.input.model.unit_001.reaction_bulk.mal_stoichiometry_liquid = stoich

More consistent would be:

cadet.root.input.model.unit_001.reaction_model_bulk = 'MASS_ACTION_LAW'
cadet.root.input.model.unit_001.reaction_bulk.mal_kfwd_bulk = kfwd
cadet.root.input.model.unit_001.reaction_bulk.mal_kbwd_bulk = kbwd
cadet.root.input.model.unit_001.reaction_bulk.mal_stoichiometry_bulk = stoich

However, this gets tricky as soon as solid phase reactions also have to be considered (which are part of the particles interface) and we still want to be able to make cross-phase reactions between liquid (in this case, bulk) phase, and solid phase...

cadet.root.input.model.unit_001.reaction_model_particles = 'MASS_ACTION_LAW'
cadet.root.input.model.unit_001.reaction_particles.mal_kfwd_solid = kfwd_solid
cadet.root.input.model.unit_001.reaction_particles.mal_kbwd_solid = kbwd_solid
cadet.root.input.model.unit_001.reaction_particles.mal_stoichiometry_solid = stoich_solid

Proposal:

Since the parameters themselves also have the suffices _bulk, _liquid, and _solid, we might simply unify the parameters reaction_model_bulk, and reaction_model_particle into one reaction_model/reaction field.

This would require:

• Implementing an adapter to convert the _bulk parameters for the lumped rate model without pores (if we continue using the particle reactions interface internally)
• Introducing a multiplex in case someone wanted to have have different reaction models (not parameters) for the different phases.
• Optional: Introducing a flag to specify if model and parameters should be used for all (liquid) phases

An interesting discussion with @lieres also led to the conclusion that in future we might want to provide even more flexibility with reactions (e.g. not only cross-phase but also cross-zone) which would also require modifying the interface in some way.

[sleweke]

Thanks for the analysis and suggestion. I generally agree.

Since the parameters themselves also have the suffices _bulk, _liquid, and _solid, we might simply unify the parameters reaction_model_bulk, and reaction_model_particle into one reaction_model/reaction field.

This suffix is not a convention (as of now). This fully depends on how the reaction model is implemented.

Introducing a multiplex in case someone wanted to have have different reaction models (not parameters) for the different phases.

I don't see how this could work. Please elaborate some more.

[schmoelder]

After some discussions, here is a proposal for a new reactions interface which would

• improve consistency
• be more modular
• allow different reaction types to be specified for a single unit operation

cadet.root.input.model.unit_000.bulk_reaction_000.reaction_model = "MASS_ACTION_LAW"
cadet.root.input.model.unit_000.bulk_reaction_000.stoich = [-1, 1]
cadet.root.input.model.unit_000.bulk_reaction_000.k_fwd = 1
cadet.root.input.model.unit_000.bulk_reaction_000.k_bwd = 1

cadet.root.input.model.unit_000.bulk_reaction_001.reaction_model = "MICHAELIS_MENTEN"
cadet.root.input.model.unit_000.bulk_reaction_001.v_max = 2.3
cadet.root.input.model.unit_000.bulk_reaction_001.sub_reaction_000.sub_reaction_model = "COMPETITIVE"
cadet.root.input.model.unit_000.bulk_reaction_001.sub_reaction_000.ki = [0, 1]
cadet.root.input.model.unit_000.bulk_reaction_001.sub_reaction_000.km = [1, 2]
cadet.root.input.model.unit_000.bulk_reaction_001.sub_reaction_001.sub_reaction_model = "NON_COMPETITVIE"
cadet.root.input.model.unit_000.bulk_reaction_001.sub_reaction_001.ki = [1, 1]

cadet.root.input.model.unit_000.particle_liquid_reaction_000.reaction_model =  "MASS_ACTION_LAW"
...

cadet.root.input.model.unit_000.particle_solid_reaction_000.reaction_model =  "MASS_ACTION_LAW"
...

cadet.root.input.model.unit_000.particle_cross_phase_reaction_000.reaction_model =  "MASS_ACTION_LAW"
...

[AntoniaBerger]

While working on enabling multiple reactions, we developed a slightly different interface than the one proposed in the previous comment.

Summary:
We now distinguish between reactions based on the phase in which they occur i.e, solid, bulk, particle/pore.
For each phase, we define the number of reaction models using: phase.nreac.

Then, we specify each reaction model as follows:

    phase.reaction_model_xxx.type = "NAME_OF_THE_MODEL"  
    phase.reaction_model_xxx.param1 = value1  
    phase.reaction_model_xxx.param2 = value2  
    ...  

Additionally, we now distinguish between intra-phase (within a single phase) and cross-phase reactions.
Cross-phase reactions are handled as a separate module, implemented as an additional "phase," (reaction_cross_phase_xxx) and can only be used within a reaction_ context.

For more details and concrete example, please refer to #92 and #453, #449.