PD Inline Formula Editor Documentation.
So here we are, explaining our brand-new, as of January 2020, Inline Formula Editors in detail.
First of all, how does everything fit together. In the beginning, Dynamic Applications are basically empty. The program starts up with the Simulation Model Selector, showing all Simulations available in the User’s Home Document Folder, where automatically a Folder for Dynamic Applications will be created during installation.
Here, in a Folder called XMILE, all built-in simulation models are copied, and further self-created derivates can be saved. These are loaded on Startup, and thus create the list of Simulations.
Starting up a Simulation.
The Freeware Version of Dynamic Applications will show a Promo Code Activation Field, as well. Here you can enter the Universal Promo Code, which will activate our Inline Formula System. It’s hidden on various pages within our Website, and contained in one Tweet within the Dynamic Idea and Roadmap Competition. Apart from that, in the product standard, the first 12 Input and Target Values will be editable, so that you can try out everything in all cases.
Small Business Developments, all Windows 10 Store Apps, and Perfect Desire will have the Formula System always on. So there’s no need for Promo Codes in these cases. The professional version will officially support creation, load and save of calculation models in x / y / t with up to 100 Input Values and 100 Target Formulas. That’s guaranteed to you by the dna license.
Now, in loading the selected Simulation, Dynamic Applications reads in the Input and Target Formula Specifications from the Simulation Model File. For each Input Value and each Target Formula, as well as for accumulating Stock Values (treated much like Targets here), a new user interface element will be created, automatically. With radio button, coloured icon symbol, Title, Unit, Value, and Mode Selector for Input Values. Finally, the whole equation system, as described within the Simulation Model File, will be evaluated and resolved. That works much like you may have learned in School, when you’ve got a set of three unknown variables, in three equations, e.g.:
- a = 4 * b + c
- b = 2 * c
- c = 15
you can now resolve:
- b = 2 * c = 2 * 15 = 30, and then:
- a = 4 * b + c = 4 * 30 + 15 = 135.
So with c = 15, now you’ve already resolved all three values.
That’s pretty much what our Universal Equation Solver Engine does, automatically, when loading Dynamic Applications. Input Values are always known numbers, so they are inserted into Target Formulas. So Target Formulas become solvable. Finally, as soon as all Target Values are known, the Simulation Model Selector disappears, and your Dynamic Application of choice is up and running.
Now since the whole Formula System is being interpreted on-the-fly, we can also do live changes.
For this to activate, you have to click on the small [ / ] Pencil icons on Top of the Input and Target Value Panels. This will replace all Radio Buttons with Pencils.
Congratulations! You’re in Editing Mode, now.
Editing Titles, Units, Values, and moving up/down Positions.
By clicking on one of the Pencils, you’ll activate the Input or Target Value’s Label Editors, as well as the Inline Formula System, which automatically opens in place of the central Time Ruler.
The SD Input or Target Value, as selected on the left or center User Interface Panel, will highlight it’s Title. So you can directly rename the item selected.
Activating a Pencil Editor will also automatically select its Radio button for you.
So the element will show up in the Result Graph, and you can follow your modifications. While the Element’s Value may be hidden during changing the Value or Formula, you can always point at the coloured Input or Target Value symbol, and see the last valid calculation shown within the item’s ToolTip.
To be able to specify Formulas, we need a way to display Input and Target Value Titles.
For this purpose, and for ease of operation, a matching Formula Symbol will be created directly from the item’s Title.
So if you change a Target Value title from ‘Gross Revenue’ to ‘Gross Margin’, it will change automatically its formula descriptor from T_GrossRevenue to T_GrossMargin, throughout the whole formula system.
See below for more.
Finally, whenever you click on the Top Pencil and so activate Pencil Editor Mode, a New Input Value and a New Target Value will appear at the bottom, automatically. This way, you can easily add new Values to your calculation. If you give them a new name, they are maintained within the Formula System. If you just leave them untouched, they will have no function, and they’ll disappear automatically as soon as you end editing by clicking on the global, on-top Pencil symbol again.
Now whenever you’ll specify and accept a new element by clicking it’s green checkmark, another New Value will appear, automatically. This way you can easily expand your Input and Target Formula System, one by one.
Finally, there’s also removal. When activating the Pencils, a small, dark-red Recycle bin symbol will appear next to it. Now if you click on that Recycle bin icon, all Editors will instantly become Recycle bin. Now select your Value of choice, and destroy it.
If that was an important value, you’ll be notified, on the spot. If you still decide to remove it, because you want to change that calculation, all Targets disabled by your removal will show the error symbol, an [ ! ] exclamation mark, automatically. So you can always see where there is work to do. Now you can correct all your remaining Formulas, as desired, and as soon as the final formula is corrected, all [ ! ] symbols will be gone.
Specifying Units, and Unit Conversions.
Next to its Title, each item also has a Unit description field.
So here you can enter a financial or physical Unit like Euro, kg, m, day, year, s, Euro / Month, or even a combined unit like m / s², km / h.
In Dynamic Applications, Units are only used for descriptive purposes. So they appear within ToolTips, as well as on the vertical axis of the Result Graph when selecting an element. But whatever you specify there, it will have no influence towards the calculation, by default. So the calculation results will not change if you change hour (h) by second (s). You can write hour, hours, h or second, sec, s as you prefer.
In theory, it would of course be possibly to apply automatic number conversions from hour to second, but then, think about converting days into months, it already would become difficult. An easy approach here would of course be to assume 30 days per month, average. However, in Dynamic Applications, for ease of operation and understandability, there is no automatic conversion. Such conversions will have the effect that every Unit must match exactly towards the internal conversion system, or there will be calculation errors. So that would require extra attention.
Instead, when using Dynamic Applications, we specify all Unit Calculations within the Formula, itself. That’s most easy and as good. So if you have one Formula using Gram (g), and one other formula using Kilogram (kg), there should be a * 1000 conversion, somewhere. If you have seconds and hours, there should be a 60 * 60, a conversion factor of 3600 within your formulas, where necessary. A separate Unit calculation system would have that same calculations, only separated. So here we have everything in one place.
Another advantage is basic understandability.
So we can talk of ‘Working hours per day’, and specify these in hours (Unit: h). Technically, if working with Unit conversions, the label would have to be called ‘Working’, and the Unit would have to be ‘h/day’, or the calculation system couldn’t resolve the Units, properly. So that’s why we keep it simple and you have one formula, and there’s no hidden calculations in the background.
To round up, we have the possibility to add any Unit description, but that will not have any effect on your calculation.
Changing Default Values.
As well as editing Titles and Units, you can also change the default Input Value. So if you change the number shown, then save the Simulation Model, it will load and run again with your preferred default value.
Since Target Values are calculated, automatically (derived from Input Values and Formula), it will not be possible to change a Target Value, by number. Instead, you’ll have to change it’s calculating formula, accordingly.
While there have been frequent questions whether it would not be possible to allow for direct manipulation of Target Values, this will not be supported. Yes. In theory, it would be possible to enter a different number, and see it’s outcome, on the spot. But that could easily bring the whole formula system out-of-order. First of all, the value shown is just one value in a 48 – to – 100 value combination, depending on the number of Time steps. If you want to change singular Input Values for a specific time, you can do that in the bottom Detail Value Table, which works much like a line of Input Cells in Excel. Just enter your numbers, one by one.
However, changing values for Targets would also mean that the incoming formula system must be cut away. Still, the Input Values in question could have effects on other Formula. This may or may not be obvious in the given case. Generally spoken, the effects of manipulating a specific Target Value’s display value would be uncertain, and almost undiscoverable (if not following all the ToolTips and thereby understanding all dependencies of the whole Formula System). So we better forget about it.
In Dynamic Applications, for clarity and understandability:
- Input Values are Parameters and can be edited with a Pencil’s click, then accepted.
- Target Values are calculated formulas and they so they can not be edited.
Moving Input and Target Values, up and down.
The final User Interface field is now replaced by these 4 symbols: up, down, undo, ok.
These will operate much as expected:
- move down will move an item down the list. It’s index nr will increase by 1.
- move up will move an item up the list. It’s index nr will decrease by 1.
- undo icon will undo your latest changes, so the icon’s name, unit and value will be restored.
- checkmark will accept all your changes. Undo will then restore the accepted value.
If you move an Input Value beyond the Top or Bottom of the list, it will toggle around, and appear on the other (Bottom / Top) side of the list, automatically.
Following each checkmark acceptance, there will be a Target Formula Evaluation for all Targets. So if you have introduced any error, all defect locations will now be shown, with their values showing -/-.
Nevertheless, the remaining Formula System shall work as specified, as far as possible.
That’s what we call Persistence.
Editing and Specifying Formulas in Dynamic Applications.
To be able to specify Formulas, we need a way to display Input and Target Value Titles.
For this purpose, and for ease of operation, a matching Formula descriptor will be created directly from the item’s Title.
So if you change a Target Value title from ‘Gross Revenue’ to ‘Gross Margin’, it will change automatically its formula descriptor from T_GrossRevenue to T_GrossMargin, throughout the whole formula system. While creating the formula descriptor, invalid characters will be ignored. For easiness of reading, words will be capitalized:
- Bread, Production Time => i_BreadProductionTime
- Bread -> Daily Sales => i_BreadDailySales
- Sales per hour => i_SalesPerHour
- Net Profit => T_NetProfit
- Time to build Well => i_TimeToBuildWell
Each Formula descriptor will be prefixed by either of i_, T_ or S_, representing Input, Target and Stock Values, respectively. So there’s a clear identification of elements in a Formula.
The very nice side-effect of this is that you never have to care for the Value’s Formula descriptor, explicitly. It will always be automatic. A small drawback that comes with this simplification will be that when creating Multi-Language Simulation Models, each Language will have its own Formula Descriptors (readable in the local language).
We recommend to create different Simulation Model Files for each language in this case. Still, it is very well possible to create a Simulation Model in one language (e.g. English), then save that reference Model to disk. Then, load it again, activate all Pencils, translate all items to German, French, Spanish or Russian Language, and save that resulting model, named in its local language. This way, the formula system will adapt automatically to each language, so you can simply translate the User Interface Titles, save it under a new name, and that’s already all. Now you have one English and one German Simulation Model.
Apart from that specific consideration, a great benefit that comes from automated Formula descriptors is that you can highlight each Formula descriptor by a single (or double) mouse click:
Now that you’ve highlighted an Input or Target Value, for easiness of operation, you can simply click on an element’s ToolTip symbol to add it right in place of that highlighted symbol, at the Cursor position.
In using the integrated [+][ – ][ * ][ / ] symbols, as well, this way you can set up any simple formula, without using the keyboard, at all. Of course, we also support brackets ( ), ^ for power, or any number you want to add or multiply. As the space for editing your formula is quite limited, these you’ll have to type in using your keyboard, though.
Please note that both editing systems (Title, Unit and Value Editors, vs. Formula Editor) are mostly independent of each other. Accepting a Formula will automatically influence a Target’s ToolTip, and changing a Title will also influence its automated Formula descriptor.
For this reason, the whole Target Formula system will be evaluated after each click on a checkmark. For easiness of operation, the Target Formula will as well be evaluated when hitting Return. So here you can already see whether you have got a valid formula, without leaving the keyboard.
The Inline Formula Editor can as well be used for editing Input Values. Here, there is no formula, so you can edit directly its value, as well as its comment. To edit an Input or Target Value’s comment, please choose ‘Comment’ in the Editing Mode selector on the left.
Creating and Editing Stock Values.
In System Dynamics, Stock Values are automated counters. There are many applications for these. The most easy explanation for a Stock Value will be a Stock of Bees. Whenever a new bee arrives, the Stock Value accumulates by 1, because there is now 1 more bee within the Stock. When 2 bees appear and fly into the Stock, it’s value will increase by 2. When 3 bees departure for collecting honey, the Stock Value will decrease by 3. So the value of a Stock is not 3, instead its value will always depend on its previous value, the value at [t-1].
If there were 100 bees in the Stock, and 3 bees would departure, we’ll now have 97 bees in stock.
Since we will have situations where we want to describe a start value, start position, or starting velocity, to name a few examples, there is another Selection Mode below ‘Stock Value’, called ‘˪ Start Value’. Here you can specify an initial value of Bees for your Stock at the starting point of your simulation, [t=0]. So you can start your simulation with 100 bees.
As well, you can use Stock Values to describe any accumulating value.
Step by Step instructions on how to create a Stock Value.
Let us define a Bank Account Balance that should accumulate your Net Profit.
First of all, delete the Bank Account Balance, should it be there. As nothing usually depends on it, that should be possible without causing any problems in the Target Formula system.
Or we could simply start from an Empty New Model.
Now, let’s hit the Pencil.
We take the free ‘New Target Value’ at the bottom, and name it ‘Bank Account Balance’. By moving it down the line once more, it will automatically toggle to the Top.
You can rename the other Target Value as ‘Net Profit’ by clicking on its Pencil, then accepting by hitting the green checkmark, before or afterwards.
Now you create your Stock Value simply by changing the item’s Operation Mode in the Mode Selector on the Inline Formula Editor, top left. In the screenshot, it still shows ‘Target Value’. Please click on it, and select ‘Stock Value’.
Now, what do we want to accumulate? – Net Profit.
With one additional click on the yellow ToolTip symbol before ‘Net Profit’, you’ll have T_NetProfit inserted in the Formula Editor.
That’s it, already! – your Stock Value will now accumulate Net Profit.
Now if you say, but you have 2500 Euro on your bank account, in the beginning, good for you. Select ‘Start Value’ and set that amount of 2500 to define the initial value, then accept.
Your Bank Account Balance should now represent in a diagonally upwards pointing line:
2500, 2503, 2506, 2509, 2512, 2515, 2518, 2521, 2524, …
As that is certainly not an attractive Profit, you can now change the Profit per Month.
In the standard New Empty Model, the first Target is calculated to be the sum of Input Value 1 and 2. So now you can enter any value for an Input, and check out the results, accumulating over time. So if you add 1000 and 2000, you’ll have earned 3000 Euros per Month, and your Bank Account Balance should go 2500, 5500, 8500, 11500, 14500, 17500, and so on. Much better.
In traditional System Dynamics, a Stock Value is assumed to have an Inflow and an Outflow. So that’s best explained by a Water Reservoir, and it works much the same.
The Inflow is always added up, and the Outflow must be substracted.
To simulate such a Stock Value, you simply specify this using ‘T_Income – T_Cost’, for example.
In Dynamic Applications, for easiness of operation, we can as well specify about any other formula. Changing its Target Mode to become a Stock Value will just care for automatically adding up all its values over time, much like a Bank Account is collecting (adding up) and the money you pay in per month, and substracting any withdrawals.
You are welcome to try out, then create any Formula System that you may desire.
A short overview on Math Formula.
As of today, the following functions are available within the Input Formula Editor.
- [+][ – ][ * ][ / ], ^, % Operator Icons:
The 4 basic math operators have an icon of their own. You can insert the operator with a Mouse click, our the Touch of your Finger on a Notebook with Touch display (there is a standard support for Touch within .NET / Windows Forms that allows you to tip on basically anything, and so create a Mouse click Event). This allows you to create typical Formulas without using the keyboard, at all. You can click the ToolTip icon of an Input or Target Value, and it will appear selected. Activating [+][ – ][ * ][ / ] on a selected Value will add that operator behind the symbol, automatically. If you then hit another one of these, it will replace the former symbol, so that there is only one operator betweet Values at a time.
In addition to these functional operators, you can also type in ^ for Power ( 2 ^ 3 = 2 * 2 * 2 = 8), and % for Mod, the remainder of a division: 7 % 3 = 7 mod 3 = floor( 2.333 ) = 2.
Defined Values: e, pi, t, time, dt, starttime, stoptime, inf:
- e = 2.718281828459045. (Euler’s number)
- pi = 3.14159265358979. (Archimedes constant for circles)
- t = time, representing the current value of the Time ruler.
- dt = delta time = 1. (for simplicity, the Time interval in Dynamic Applications is dt = 1).
- starttime = 0. (for simplicity, all simulations in Dynamic Applications start from t = 0).
- stoptime = the maximum value of the Time ruler. (this can be configured in Settings).
- inf = infinity, an unbelievably high number. Rarely useful.
Mathematical Functions with one operand:
- abs( x ) returns the absolute (Positive) part of x. It removes any (-) sign.
- ceiling( x ) returns the next positive integer number: ceiling( 1.01 … 1.99 ) => 2.
- exp( x ) returns e ^ x, where e = 2.718281828459045.
- floor( x ) returns the integer part of x: floor( 1.01 … 1.99 ) => 1.
- int( x ) returns the integer part of x. int( 1.01 … 1.99 ) => 1. Same as floor().
- round( x ) rounds x: round( 1.01 … 1.49 ) => 1 , round( 1.50 … 1.99 ) => 2.
- sign( x ) returns the sign of x: 1 for positive numbers, 0 for 0, -1 for negative numbers.
- sin( x ), cos( x ), tan( x ) return the Sinus, Cosinus, and Tangens function values.
- arcsin( x ), arccos( x ), arctan( x ) return the inverse trigonometric function values.
- sinh( x ), cosh( x ), tanh( x ) return the hyperbolic trigonometric function values.
- sqrt( x ) returns the Square Root of x.
Mathematical Functions with 2 operands:
- min( x, y ) returns the minimum (smaller) value of x and y: min( 4, 7 ) = 4.
- max( x, y ) returns the maximum (larger) value of x and y: max( 4, 7 ) = 7.
Conditional If-Then-Else Expressions, with 3 operands:
- ifzero( a, b, c ) <=> if( a == 0 then b else c )
- ifpositive( a, b, c ) <=> if( a > 0 then b else c )
These functions allow you to depend your calculation on certain conditions.
In Dynamic Applications, there are only value expressions, so a, b, and c can be any value itself, or be a formula that calculates some value. The if statement will return the value of statement b, if the condition ifzero(a) is true, or it will return value of statement c, if the condition ifzero(a) was false.
For example, the Total Cost of Producing a Tool may depend on whether you have got Employees. If you have Employees, they’ll have to be paid for their Work Time. If you produce on a do-it-yourself basis, you can just work as much as you want, and all the Profit is yours, anyway.
This condition can be represented as follows:
T_ProcessCost = ifzero( i_Employees, i_MaterialCost, i_MaterialCost + T_WorkTime * i_SalaryPerHour)
The expression works much like the well-known if – then – else clause in other languages.
ifzero( i_Employees , … , … ) will first check if i_Employees are zero.
- If (i_Employees == 0 ), it will return the 2nd value (i_MaterialCost).
- If (i_Employees <> 0 ), it will return the third value (the value of the small formula).
An alternative representation with same calculation result would be:
T_ProcessCost = i_MaterialCost + ifzero( i_Employees, 0, T_WorkTime * i_SalaryPerHour)
We could also use the ifpositive( a, b, c ) function to calculate our formula:
T_ProcessCost = i_MaterialCost + ifpositive( i_Employees, T_WorkTime * i_SalaryPerHour, 0)
- If (i_Employees > 0), it will return i_MaterialCost + T_WorkTime * i_SalaryPerHour.
- If (i_Employees <= 0), it will return i_MaterialCost.
All Plain Math Formulas, explained.
Now we hope that you have seen that everything we have defined in The Desire Language (that’s how we call our small formula language) is quite simple and straightforward, as desired.
Future improvements would be to support a traditional if( a == b then c else d ) statement with <, >, ==, <=, >= and <> comparators. Further mathematical expressions could be added to The Desire Language where necessary. However, since simplicity and ergonomy are our main targets, we don’t really plan to make everything too complicated.
It can be done on request, i.e. for a certain customer requirement. Feel free to ask.
In specifying our functionality, we have oriented us on XMILE, an international standard for representing System Dynamics calculation models, as published by OASIS. It has been developed in cooperation with the System Dynamics Society. As far as we’ve heard, from 2018, it’s finalized. So herefrom we use to derive our small programming language.
Since there are quite a few competitors out there, and about every company will have implemented their own little secrets, unique selling points, and extensions, we can not give a warranty that it would or will be possible to import such simulation models here, even if they’ve been stored in XMILE. There are just too many options. It works where and as far as it works. We can help you with converting such existing files on request. Contact us here.
You are welcome to try out everything, and create any Formula System that you may desire.
What you can expect is that you can create a simulation model with Dynamic Applications, then you can save it to disk, and you shall be able to load it back and run it on the next day. If it doesn’t work, you can report that as a bug, and we’ll try to fix it as soon as possible.
If you want, you can publish your results on the Internet, free of charge.
If you want to make profit from using Dynamic Applications, we expect you to acquire our Professional Business Model Development Environment, Small Business Developments, or Perfect Desire. As well, our Windows 10 Store Apps, which are available from 99 cent, will have the full-featured Formula System activated by default. These are intended for personal usage.
For Professionals, it’s 25 Euro per User Installation per Year. So that’s basically a small Tribute for me, the Founder. For creating the whole ecosystem of Dynamic Applications, from 2016. Apart from that, we’ll be happy to create any specific application that you may desire. For example, our formula system could be represented by specific result graphs in certain applications. For serious interest, we are happy to make an offering at 25 Euro/h.
So now you know almost everything about how Dynamic Applications are created.
If you need any specific Support, or you’ve got additional questions, we’re here to help.
Martin Bernhardt and his small Family.