How to Implement New Module in STATE system

[rburghol]

• Create object handler for new model component
  • Add a file to hold component class definition, parser and runtime code in the HSP2 directory
    • create code file named as snake_case om_[new_component_name].py
    • Ex: Legacy special ACTION https://github.com/HARPgroup/HSPsquared/blob/develop-specact-1/HSP2/om_special_action.py
    • Note: code will soon be in HSP2/specl/ directory see STATE sub-module refactor #126
  • Create class as sub-class of ModelObject in om_[new_component_name].py:
    • name object as CamelCase i.e. [NewComponentName]
    • Give a unique, integer optype in the __init__() method
    • extend method NewComponentName.parse_model_props() if supporting custom json-type model_props array
    • extend NewComponentName.tokenize() method to add necessary integer keys to run in @njit runtime
    • tbd: extend method NewComponentName.parseUCI() if loadable from classic UCI
    • ex: class SpecialAction(ModelObject):
  • Add @njit compatible runtime evaluation function with prefix step_ (ex: step_[new_component_name]())
    • minimum arguments: (op, state_ix)
    • may have any/all of the following arguments: ( op, state_ix, dict_ix, op_tokens, step)
    • Ex: step_special_action()
  • (optional) Add @njit compatible runtime pre-eval function with prefix prestep_
• Add Model Tokenizer and Run-time Support in om.py:
  • Import the file containing the class def and runtime code
    • from HSP2.om_[new_model_object] import *
    • Ex: from HSP2.om_special_action import *
  • Insure support in function model_class_loader()
    • Most often, all that is needed here is to add the following 2 lines:
      • if object_class =='NewModelObject':
      • model_object = NewModelObject(model_props.get('name'), container, model_props)
      • Ex: SpecialAction
  • Add execution handling in
    • step_one()
      • Ex: step_special_action()
    • (optional) pre_step_model()
      • This is used for things that need to happen at the very beginning of a timestep
• (optional) Insure that components are loaded into the state['model_data] dictionary at model startup in main.py
  • If the new model component data is not stored in the already loaded json file, or is stored in an hdf5 table that is not already loaded via a function, add function to load this data in main.py
    • Ex: state_load_dynamics_specl()