Package: bms-tree-modules
bms-tree-modulesThe package contains the generic building blocks for the period-based Banking Management Simulation Games developed by the Institue of Banking & Finance (University of Zurich, Switerland).The package delivers the game building blocks: Node, Tree, Team, Config, Curves, Module.
These classes can be used to implement a simulation without having to setup the complete tree data structure logic from scratch.
The implementation can extend the classModulewhich takes JSON as input and allows to create a tree data structure recursively from it.
All manipulations of the tree should be implemented in the actual implementation/simulation class.This package has been created as part of the Banking Management Simulation Game (BMS20) project at the Institue of Banking & Finance and Institute of Informatics (University of Zurich).RequirementsPython 3.8pippipenvUsing the Library (in a Simulation)InstallationRunpipenv install bms-tree-modulesorpip install bms-tree-modulesto install the package.How to create a new simulation?Create a new file in which you're going to implement the logic of the simulation.frombms-tree-modules.moduleimportModuleclassSimulationClassName(Module):def__init__(self,period_input):super().__init__(period_input)withopen("/path/to/json_input.json","r")asfile:# read file and load json string as dictperiod_input=json.loads(file.read())# create new simulationsim=SimulationClassName(period_input)JSON input format requriementsThe Module class requires theperiod_inputto be JSON and in the following format.
All parts described separately below need to be in the same input file.Curve Configuration{"curve_assignments":[{// key how the curve shall be retrievable in your code"curve_slot_key":"KEY_USED_INTERNALLY_TO_RETRIEVE_THE_CURVE","curve_assigned":{// The coefficients of the sensitivity curve// The curve will be create as a lambda function"coefficients":[0.12,7.5,200.0],}},Team InputFor every team taking part in the period-based simulation, theteamsarray needs to contain a separate entry."teams":[{"team_id":0,"decisions":[// the decisions the teams made{"key":"LOANS_MARK_UP_RATING_A","value":0.01},],"tree_input":{"name":"root","value":0,"description":"Team0_RoundInput_PeriodTimestamp?","children":[{"name":"BS","description":"The Balance Sheet","value":0,"children":[{Team ObjectEvery team object consists of:team_id: intdecisions: List of Decision Objectstree_input: Node Object (root node)Decision ObjectEvery decision objects consists of:key: stringvalue: floatThe keys must be the same across all teams and each team must contain all keys that exist.Node ObjectEvery object inside thetree_inputis a Node object which needs to contain the following:name: stringvalue: floatdescription: stringchildren: List of other child nodes (or empty)Leaf Node Configuration ValuesFor at least all leaf-nodes (nodes which don't have childern i.e. an empty children array), a node configuration object needs to be provided.What is an effect?An effect is a factor which influences how the value of a leaf-node is changed from statet0to statet1(i.e. the change from one period to the next).
A leaf-node can have many different effects.
The results of all effects are summed and added/subtracted from the leaf-nodes input value -> new value.Each effect can have multiple configuration values -> these values are the same for all teams.
An example of a configuration value is theCURVEmapping which tells the simulation which sensitivity curve to use during the computation of the new effect value.
Others are,MIN(lower-limit),MAX(upper-limit),WEIGHT(contribution factor) which need to be considered when computing the effects value."config":[{"name":"BS_ACT_LOANS_RATING_A","description":"Description of the configuration values","effects":[{"name":"SERVICE_QUALITY","values":[{"key":"MIN","value":0.0},{"key":"MAX","value":0.1},{"key":"WEIGHT","value":0.5},{"key":"CURVE","value":"SERVICE_QUALITY_ASSET_SIDE"}]}]},Developing the LibraryFor developers wanting to extend this work, the following parts might give some insights.Installation InstructionsRunpipenv install --devto install all dependencies
Runpipenv shellto enter the virtualenv created by pipenv for this project.PS: if the installation doesn't work use--presince some packages might only be in pre-release state.How to build a new release?Make sure you're inside the previously created pipenv.Create the build (package)Runpython3 setup.py sdist bdist_wheelwhich creates adist/andbuildfolder.Upload the packageRunpython3 -m twine upload dist/*to upload to the PyPi repository.In order for the upload to work, you need to create an API token to access PyPi.
Use__token__for username andpypi-...as password.PS: the credentails can also be stored inside a$HOME/.pypircfile.[pypi]
  username = __token__
  password = pypi-...Official DocumentationFor more information have a look at the offical documentation:https://packaging.python.org/tutorials/packaging-projects/ChangelogThe following sections documents the changes across the different versions.📦 v0.2.1✨ New Featureadd: helper field to Decision(allows to hide internal helper decisions when returning state to dict)📦 v0.2.0✨ New Feature & Breaking ChangeDecisions are no longer key:value pairsNew Class Decisions & Decision(replaces decisions <dict> in Team with List[Decision])📦 v0.1.4✨ New Featureadd decisions to Teamto_dict()function(to be able to pass it back in ResponseDTO)📦 v0.1.3🐛 Bug Fixa team can be retrieved by its team_id(not the index in the teams list)📦 v0.1.2update README & package description📦 v0.1.1initial package creation