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
#define SWMM_RXN_SCOPE_SUBCATCHMENT 4 
#define SWMM_RXN_SCOPE_SUBSURFACE 3   
 
/* 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).
 * Mutators use operation-specific validation. Changes affecting expression
 * indexes/source text recompile with reaction/registry snapshots; simple
 * coefficient/source-value assignments do not recompile. Species add/remove
 * rebuild the registry MSX block, and referenced species removal is refused.
 * See each operation for side effects and rollback scope. --------------------- */

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_rain_conc_get(SWMM_Engine engine, int species_idx, double* value);
SWMM_ENGINE_API int swmm_reaction_rain_conc_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 */