From 44e33b0561e3622359e89d134a4254bb02ca01e4 Mon Sep 17 00:00:00 2001 From: Dylan McDowell Date: Mon, 1 Apr 2024 16:43:01 -0600 Subject: [PATCH 1/2] Custom Function Documentation --- doc/guide/heron_guide.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/doc/guide/heron_guide.md b/doc/guide/heron_guide.md index fc024f99..133b4256 100644 --- a/doc/guide/heron_guide.md +++ b/doc/guide/heron_guide.md @@ -160,7 +160,7 @@ HERON allows users to create their own functions that perform computations durin Currently, these functions can only deal with computations that do not occur during the dispatch optimization. For example, a user can write a function that determines the `` parameter of a component's cashflow because cashflows are not computed during the inner dispatch optimization. -Currently, a user would _not_ be able to write a custom transfer function that informs the dispatcher on how resources are transformed while moving between components of the specified system. This is because transfer functions are required during the dispatch of the system and would require the user to write the function in a way that could be interpreted by our underlying optimization library. **While this feature is not currently available, it may be made available in the future.** +Currently, a user would _not_ be able to write a custom transfer function that informs the dispatcher on how resources are transformed while moving between components of the specified system. This is because transfer functions are required during the dispatch of the system and would require the user to write the function in a way that could be interpreted by our underlying optimization library. To be more specific, a user would **not** be able to use a custom function within a `` XML node in the HERON input file. **While this feature is not currently available, it may be made available in the future.** Users can see examples of these custom functions in the [FORCE use case repository.](https://github.com/idaholab/FORCE/tree/main/use_cases) @@ -173,9 +173,9 @@ A custom function utilized in a HERON input file requires two input parameters t * `data`: A Python dictionary containing information related to associated component that is calling the function. * `meta`: A Python dictionary containing information pertaining to the case as a whole. -It is possible to specify ancillary functions in your python file that do not follow the API conventions, but realize that functions called in your HERON input file will require this specification. +It is possible to specify ancillary functions in the python file that do not follow the API conventions, but understand that functions called from the HERON input file will require this specification. -For example, suppose a user wanted to write a function that computed the reference price for a particular component. In their input file under the `reference_price` node they would write: +For example, suppose a user wanted to write a function that computed the reference price for a particular component based the current year of the project. In the input file, under the `` node, the user would write: ```xml @@ -185,20 +185,31 @@ For example, suppose a user wanted to write a function that computed the referen ... - + [path/to/python/functions/file] ``` -Then in a file created by the user, they would write the following function: +Then in a file created by the user, they might write the following function: ```python def get_price(data, meta): - + """Determine the time-dependent price multiplier and return new reference_price.""" + # For the first ten years of the project we can sell for a higher price + year = meta['HERON']['active_index']['year'] + if year <=10: + multiplier = 3 + else: + multiplier = 1.5 + result = 1000 * multiplier return {"reference_price": result}, meta ``` +In the above code block, the function starts by accessing data from the `meta` parameter to determine what the current year is within the simulation. Then the function determines the multiplier based on the current year of the simulation. If the simulation is within the first ten years of the project timeline, then it sets a higher multiplier, otherwise it sets the multiplier lower. Finally, the function stores the newly computed `reference_price` into a dictionary that is returned by the function. This value will then be used as the `` within the component that this function is called from within the input file. + + + From 06230eaca134b2bc8eda46ed094a1bd0618992c2 Mon Sep 17 00:00:00 2001 From: Dylan McDowell Date: Mon, 1 Apr 2024 16:49:30 -0600 Subject: [PATCH 2/2] Edits --- doc/guide/heron_guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/guide/heron_guide.md b/doc/guide/heron_guide.md index 133b4256..3913bcfb 100644 --- a/doc/guide/heron_guide.md +++ b/doc/guide/heron_guide.md @@ -215,3 +215,4 @@ In the above code block, the function starts by accessing data from the `meta` p ### Custom User Specified Dispatch +**Under Construction** \ No newline at end of file