openswmm_reactions.h

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0
 *
 * Copyright 2026 Caleb Buahin
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

 
#ifndef OPENSWMM_REACTIONS_H
#define OPENSWMM_REACTIONS_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* Expression scopes for validation. */
#define SWMM_RXN_SCOPE_TERM 0
#define SWMM_RXN_SCOPE_PIPE 1
#define SWMM_RXN_SCOPE_TANK 2
 
/* Expression forms — mirrors ReactionExprForm. */
#define SWMM_RXN_FORM_NONE    0
#define SWMM_RXN_FORM_RATE    1
#define SWMM_RXN_FORM_EQUIL   2
#define SWMM_RXN_FORM_FORMULA 3

SWMM_ENGINE_API int swmm_reaction_validate_expression(SWMM_Engine engine,
        int scope, const char* expr, char* errbuf, int buflen, int* col_out);
 
/* ---- Model discovery (require an engine with a parsed model) ----------- */

SWMM_ENGINE_API int swmm_reaction_species_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_reaction_species_get(SWMM_Engine engine, int idx,
        char* name, int name_len, int* is_wall,
        char* units, int units_len, double* atol, double* rtol);

SWMM_ENGINE_API int swmm_reaction_coeff_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_reaction_coeff_get(SWMM_Engine engine, int idx,
        char* name, int name_len, int* is_param, double* value);

SWMM_ENGINE_API int swmm_reaction_term_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_reaction_term_get(SWMM_Engine engine, int idx,
        char* name, int name_len, char* expr, int expr_len);

SWMM_ENGINE_API int swmm_reaction_expr_get(SWMM_Engine engine, int scope,
        int species_idx, int* form, char* expr, int expr_len);

SWMM_ENGINE_API int swmm_reaction_option_get(SWMM_Engine engine,
        const char* key, char* value, int value_len);
 
/* ---- CRUD (E-C2) — BUILDING/OPENED only (rows only seed at start).
 * Every mutator validates eagerly: the whole system is recompiled before
 * the call returns, and a mutation that leaves any expression uncompilable
 * is rolled back and refused (SWMM_ERR_BADPARAM) — the GUI can never store
 * an uncompilable model (D-RC5). Species add/remove rebuild the species
 * registry's MSX block in place (D-RC3); removal of a species still
 * referenced by any compiled expression is refused. --------------------- */

SWMM_ENGINE_API int swmm_reaction_species_add(SWMM_Engine engine,
        const char* name, int is_wall, const char* units, double atol,
        double rtol);

SWMM_ENGINE_API int swmm_reaction_species_remove(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_reaction_coeff_add(SWMM_Engine engine,
        const char* name, int is_param, double value);

SWMM_ENGINE_API int swmm_reaction_coeff_set_value(SWMM_Engine engine, int idx,
        double value);

SWMM_ENGINE_API int swmm_reaction_coeff_remove(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_reaction_term_add(SWMM_Engine engine,
        const char* name, const char* expr);

SWMM_ENGINE_API int swmm_reaction_term_set_expr(SWMM_Engine engine, int idx,
        const char* expr);

SWMM_ENGINE_API int swmm_reaction_term_remove(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_reaction_expr_set(SWMM_Engine engine, int scope,
        int species_idx, int form, const char* expr);

SWMM_ENGINE_API int swmm_reaction_option_set(SWMM_Engine engine,
        const char* key, const char* value);
 
/* ---- Initial quality (GLOBAL + the E-B NODE/LINK rows) ----------------- */
 
SWMM_ENGINE_API int swmm_reaction_init_global_get(SWMM_Engine engine,
        int species_idx, double* value);
SWMM_ENGINE_API int swmm_reaction_init_global_set(SWMM_Engine engine,
        int species_idx, double value);
SWMM_ENGINE_API int swmm_reaction_init_elem_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_reaction_init_elem_get(SWMM_Engine engine,
        int entry_idx, int* is_link, int* elem_idx, int* species_idx,
        double* value);
SWMM_ENGINE_API int swmm_reaction_init_elem_set(SWMM_Engine engine,
        int is_link, int elem_idx, int species_idx, double value);
SWMM_ENGINE_API int swmm_reaction_init_elem_remove(SWMM_Engine engine,
        int entry_idx);
 
/* ---- Whole-file text surface (E-C3) — the GUI text tab's contract.
 * serialize -> apply_text -> serialize is byte-identical (D-RC6). -------- */

SWMM_ENGINE_API int swmm_reactions_serialize(SWMM_Engine engine, char* buf,
        int buflen, int* needed_len);

SWMM_ENGINE_API int swmm_reactions_check_text(SWMM_Engine engine,
        const char* text, char* errbuf, int buflen);

SWMM_ENGINE_API int swmm_reactions_apply_text(SWMM_Engine engine,
        const char* text, char* errbuf, int buflen);

SWMM_ENGINE_API int swmm_reactions_save(SWMM_Engine engine,
        const char* path_or_null);
 
/* ---- Static vocabulary (no engine handle needed) ----------------------- */

SWMM_ENGINE_API int swmm_reaction_hydvar_count(void);

SWMM_ENGINE_API int swmm_reaction_hydvar_get(int idx, char* name,
        int name_len, char* description, int desc_len);

SWMM_ENGINE_API int swmm_reaction_function_count(void);

SWMM_ENGINE_API int swmm_reaction_function_get(int idx, char* name,
        int name_len, int* arity);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_REACTIONS_H */