Add organic modifier LangmuirLDF binding

[Kats1247]

A slightly transformed equilibrium approach to the Langmuir isotherm that accounts for gradient conditions. When disabling kinetics IS_KINETIC = 0, kkin has still an impact on the output.

Edit: This PR is a follow-up to a discussion in our Forum.

[schmoelder]

Hi and thanks for your PR. For consistency, could you please revert the changes to the parameter names? I know it's superfluous, but currently we would like to stick to the convention of a parameter prefix (i.e. MCLLDF_).

Also, it might be a good idea to add some tests s.t. we can be more confident with the implementation. If you need help, please feel free to reach out or to visit on of our upcoming Office Hours.

[Kats1247]

Dear Johannes, Thank you for your email. Sorry for the late reply, I was out of office until today. I will revise the code and I will let you know. Best, Kostas

…

On Sun, 24 Mar 2024, 08:42 Johannes Schmölder, ***@***.***> wrote: Hi and thanks for your PR. For consistency, could you please revert the changes to the parameter names? I know it's superfluous, but currently we would like to stick to the convention of a parameter prefix (i.e. MCLLDF_ ). Also, it might be a good idea to add some tests s.t. we can be more confident with the implementation. If you need help, please feel free to reach out or to visit on of our upcoming Office Hours <https://forum.cadet-web.de/t/introducing-office-hours/518>. — Reply to this email directly, view it on GitHub <#171 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BEAHZOR4YTOMCS5PKCEL4ITYZ2GYTAVCNFSM6AAAAABDXDMEEGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMJWG4ZTOMRQGQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[Kats1247]

Hi I committed the changes to the code. After a few tests I've done on Python, it seems to run smoothly.

[schmoelder]

Hi, thanks for your input.

Could you please also add tests and documentation to your PR?

[Kats1247]

Hi @schmoelder, how can I upload tests and what kind of tests are considered adequate?

[ronald-jaepel]

Hi @Kats1247,

sorry for the delay :) and thank you again for your contribution to the CADET project.

Tests

Creating tests

the tests are part of the cadet code. I''ll turn this comment into a guide in the future, but for now, here's a comment:

The binding model tests are in tests\BindingModels.cpp. Therein you need to add or adapt one of the tests with the CADET_BINDINGTEST function. Because you are modifying an existing binding model, you can modify the existing MULTI_COMPONENT_LANGMUIR_LDF test, that I've also appended below:

CADET_BINDINGTEST("MULTI_COMPONENT_LANGMUIR_LDF", "EXT_MULTI_COMPONENT_LANGMUIR_LDF", (1, 1), (1, 0, 1), (1.0, 2.0, 0.0, 0.0), (1.0, 3.0, 2.0, 0.0, 0.0), \
	R"json( "MCLLDF_KEQ": [1.14, 2.0],
		"MCLLDF_KKIN": [0.004, 0.008],
		"MCLLDF_QMAX": [4.88, 3.5]
)json", \
	R"json( "MCLLDF_KEQ": [1.14, 1.0, 2.0],
		"MCLLDF_KKIN": [0.004, 2.0, 0.008],
		"MCLLDF_QMAX": [4.88, 3.0, 3.5]
)json", \
	R"json( "EXT_MCLLDF_KEQ": [0.0, 0.0],
		"EXT_MCLLDF_KEQ_T": [1.14, 2.0],
		"EXT_MCLLDF_KEQ_TT": [0.0, 0.0],
		"EXT_MCLLDF_KEQ_TTT": [0.0, 0.0],
		"EXT_MCLLDF_KKIN": [0.0, 0.0],
		"EXT_MCLLDF_KKIN_T": [0.004, 0.008],
		"EXT_MCLLDF_KKIN_TT": [0.0, 0.0],
		"EXT_MCLLDF_KKIN_TTT": [0.0, 0.0],
		"EXT_MCLLDF_QMAX": [0.0, 0.0],
		"EXT_MCLLDF_QMAX_T": [4.88, 3.5],
		"EXT_MCLLDF_QMAX_TT": [0.0, 0.0],
		"EXT_MCLLDF_QMAX_TTT": [0.0, 0.0]
)json", \
	R"json( "EXT_MCLLDF_KEQ": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_KEQ_T": [1.14, 1.0, 2.0],
		"EXT_MCLLDF_KEQ_TT": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_KEQ_TTT": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_KKIN": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_KKIN_T": [0.004, 2.0, 0.008],
		"EXT_MCLLDF_KKIN_TT": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_KKIN_TTT": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_QMAX": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_QMAX_T": [4.88, 3.0, 3.5],
		"EXT_MCLLDF_QMAX_TT": [0.0, 0.0, 0.0],
		"EXT_MCLLDF_QMAX_TTT": [0.0, 0.0, 0.0]
)json", \
	1e-10, 1e-10, CADET_NONBINDING_LIQUIDPHASE_COMP_UNUSED, CADET_COMPARE_BINDING_VS_NONBINDING)

The syntax is defined in the header file tests\BindingModels.hpp:

/**
 * @brief Emits tests for a binding model that can have external function dependence and has a non-binding and an all-binding variant
 * @param modelName Identifier of the model as string (e.g. "LINEAR")
 * @param extModelName Identifier of the externally dependent model as string (e.g. "EXT_LINEAR")
 * @param allBinding Array with number of bound states of the all-binding variant in parentheses (e.g., (1, 1, 2))
 * @param someNonBinding Array with number of bound states of the non-binding variant in parentheses (e.g., (1, 0, 2))
 * @param stateAll Array with full state vector (liquid and solid phase) of the all-binding variant in parentheses
 * @param stateSomeNon Array with full state vector (liquid and solid phase) of the non-binding variant in parentheses
 * @param configAll Interior of a JSON object block with parameters for the all-binding variant
 * @param configSomeNon Interior of a JSON object block with parameters for the non-binding variant
 * @param extConfigAll Interior of a JSON object block with parameters for the externally dependent all-binding variant
 * @param extConfigSomeNon Interior of a JSON object block with parameters for the externally dependent non-binding variant
 * @param consInitTol Error tolerance for nonlinear solvers in consistent initialization
 * @param consInitCheckTol Error tolerance for residual check in consistent initialization
 * @param usesNonBindingLiquidPhase Determines whether a test for all-zero Jacobian columns belonging to non-binding components is created
 * @param cmpBndVsNonbnd Determines whether a test for all-binding vs non-binding variant (Jacobian and residual) is created
 */
#define CADET_BINDINGTEST(modelName, extModelName, allBinding, someNonBinding, stateAll, stateSomeNon, configAll, configSomeNon, extConfigAll, extConfigSomeNon, consInitTol, consInitCheckTol, usesNonBindingLiquidPhase, cmpBndVsNonbnd) 

basically, you'll need to change the number of bound states (depending on if the mobile phase organic modifier can bind), and add the some values for the extra parameters you've added to the model. These just need to be some "reasonable" values that produce sensible results when used with your isotherm.

Running tests

If you want to run tests in CADET-Core you need to ensure that in the CMakeSettings.json file in the DEBUG:

1. the "cmakeCommandArgs" contain:
   1. -DENABLE_TESTS=ON to enable building the test runner
   2. -DENABLE_STATIC_LINK_LAPACK=ON -DENABLE_STATIC_LINK_DEPS=ON to create statically linked dependencies
2. "variables" contains:

  {
    "name": "HDF5_USE_STATIC_LIBRARIES",
    "value": "1",
    "type": "STRING"
  },
  {
    "name": "BUILD_SHARED_LIBS",
    "value": "0",
    "type": "STRING"
  },

Then you can find the testRunner(.exe) in CADET-root/build/test/Debug or CADET-root/build/test/Release.
In a cmd or bash terminal run: testRunner.exe [MULTI_COMPONENT_LANGMUIR_LDF] (or replace MULTI_COMPONENT_LANGMUIR_LDF with the relevant filter term).

If you run into problems with that feel free to ask again or join us at the monthly Office Hours.

Documentation

All binding models need documentation. These are stored in the doc/interface/binding and doc/modelling/binding directories. The modelling folder contains the pages related to the model in general such as this one and the interface folder contains the pages related to how the model interface is designed in CADET such as this one. Please update the documentation for the changes you've made to the MULTI_COMPONENT_LANGMUIR_LDF pages.

Thank you. :)