Handleiding interactieve elementen

Interactieve elementen bieden de modelleurs de mogelijkheid de regels voor een interactieve omgeving op te zetten. Hiermee kan een gebruiker aan de voorkant zelf experimenteren met de gevolgen die verschillende instellingen hebben op een casus.

Deze handleiding beschrijft de verschillende functionaliteiten van interactieve elementen en wat daar onder hangt. Sommige features staan hier al wel beschreven, maar zijn i.v.m. de tijdelijke ontwikkelstop nog niet geimplementeerd. Deze features staan schuingedrukt aangegeven.

Interactief element

Een interactief element bestaat uit een input element gecombineerd met een set regels. De gebruiker kan aan de voorkant een waarde selecteren welke dan wordt meegegeven aan de regels, waarmee het scenario wordt gemodificeerd en naar AnyLogic wordt gestuurd. De logica van de interactieve elementen wordt uitgevoerd in de volgorde waarin ze op de pagina zijn neergezet.

De mogelijke input elementen zijn:

Slider

Een slider heeft een min- en max waarde, een stapgrootte, en een set aan regels.

Single select / radio button

Een single select heeft meerdere opties waar er door de gebruiker één van geselecteerd kan worden. Elke optie heeft een waarde (heet "option" in het CMS), een label (wat de gebruiker te zien krijgt) en een set van regels. Bij het selecteren van een optie worden de regels die er onder hangen uitgevoerd in combinatie met de ingestelde waarde (option). De label is wat de gebruiker te zien krijgt

Multiselect

Hetzelfe als een single select, maar een gebruiker kan meerdere opties tegelijkertijd selecteren. De volgorde waarin deze opties worden uitgevoerd is niet gegarandeerd.

Waarden meegeven in de CMS

Wanneer interactieve elementen worden geplaatst op een pagina kunnen er waarden worden meegegeven.

Default waarden

Een default waarde toont het element met deze waarde en deze wordt ook meegestuurd. Een gebruiker kan deze default waarde overschrijven. Een default waarde geldt altijd alleen in de section waarin deze is aangemaakt.

Target waarden

Met target values heb je de mogelijkheid om een interactief element met een waarde mee te geven aan alle onderliggende sections op een pagina. Dit werkt als volgt:

• het element wordt onzichtbaar meegegeven aan alle onderliggende sections.
• als hetzelfde element met een nieuwe target value in een onderliggende section wordt toegevoegd overschrijft dit de target value voor alle sections die daar weer onder liggen.
• als het element zichtbaar in een section wordt aangemaakt wordt de target value niet gebruikt.

De volgorde van prioriteit waarden

Voor zichtbare elementen:

• input van de gebruiker
• default value meegegeven aan het element in de CMS op pagina niveau
• indien geen default waarde: 0 of eerste optie.

Voor ontzichtbare elementen:

• default value meegegeven aan het element in de CMS op pagina niveau (deze geldt alleen voor de sectie waarin het element wordt toegevoegd).
• target value (deze geld voor alle onderliggende secties).
• indien geen waarde - dan wordt het element niet meegestuurd met de API call om de KPIs te berekenen.

In geval van multi-select kunnen er target values én default values worden meegegeven aan een interactive input. De target values verhuizen mee naar de volgende sectie, de default values gelden alleen voor de huidige sectie.

Regels

Met een regel kan een modelleur instellen op welke delen van het scenario welke bewerkingen moeten worden uitgevoerd. Binnen een regel kan je een model type, optioneel model subtype en filters instellen om aan te geven op welke objecten binnen het scenario de regel van toepassing is. Hierna kan je acties definieren om in te stellen welke aanpassingen op de geselecteerd objecten moeten worden uitgevoerd. Verder wordt het ook mogelijk om de waarde dat vanuit het interactief element wordt meegegeven (bijv. een slider waarde) binnen een regel te transformeren (schalen, ophogen, delen, etc.)

Value transform

Onder een regel kunnen meerdere "value transforms" gehangen worden, die de waarde van het interactief element binnen deze regel kunnen aanpassen. De verschillende mogelijkheden zijn:

- Value Translate

Voeg een bepaald getal toe aan de waarde van het interactief element. Mag ook negatief zijn.

- Value Scale

Schaal de waarde met een bepaalde factor

- Value Map Range

Map een range naar een andere range. Als bijv. je slider van 0 tot 10 loopt vul je dit in in de "value min" en "value max" velden, en daarna kan je laten zien naar welke andere range je dit wilt mappen. Dit betekent dat als de waarde van het interactief element gelijk is aan "value min", dan wordt die veranderd naar de waarde ingevuld voor "new range min", en idem voor de max velden.

- Round

Rondt de waarde af naar een heel getal. Hier zijn 3 mogelijke varianten, ROUND, CEIL en FLOOR.

Er kunnen meerdere value transforms achter elkaar worden toegepast, en ze worden altijd in de bovenstaande volgorde uitgevoerd.

Filter

Met een filter kan je een filtering aanbrengen op de objecten van het ingestelde model (sub)type binnen het huidige scenario. De huidig ondersteunde filters zijn:

- AttributeFilter

Selecteer objecten waarvan een bepaald attribuut in het model (niet) gelijk, groter of kleiner is dan een vooraf ingestelde waarde

- RelationAttributeFilter

Selecteer objecten waarvan een attribuut van een child item of parent item voldoet aan een bepaalde conditie. Dit werkt alleen op de eerste orde relaties. Deze kan ook geinvert worden, dus selecteer objecten die niet een bepaalde relatie met condities hebben.

- SecondOrderRelationAttributeFilter

Selecteer objecten waarvan een attribuut van een child item of parent item en daar weer de child item of parent item voldoet aan een bepaalde conditie. Dit werkt alleen op de tweede orde relaties. Deze kan ook geinvert worden, dus selecteer objecten die niet een 2e order relatie met condities hebben.

❗❗❗ Wanneer je een second order relation type aan wilt passen in een filter moet je altijd de complete boom doorlopen. Dus Relation field -> Relation field subtype -> Second order relation field -> Second order relation field subtype en dan klopt alle data. ❗❗❗

- RelationExistsFilter

Selecteer objecten waar een bepaalde relatie aanwezig is. Dit werkt alleen op de eerste orde relation. Deze kan ook geinvert worden, dus selecteer objecten die niet een bepaalde relatie hebben.

- DiscreteAttributeFilter

Hetzelfde als een attribute filter, maar geldt alleen voor enumerations met een dropdown. Dus bijv. een keuze uit de verschillende opties voor ConsumptionAssetType voor een asset.

Filter subselectie

Met deze opties kan je een subselectie van de gefilterede resultaten nemen. Er zijn twee modi: ABSOLUTE en RELATIVE. Het eerste houdt in dat het absolute getal als waarde wordt genomen, en het tweede houdt in dat een bepaald percentage van de gefilterde resultaten wordt gebruikt als hoeveelheid. Dit percentage moet een getal tussen 0 en 100 zijn.

- Skip

Sla de eerste $n$ elementen over in de gefilterde lijst. $n$ is handmatig in te stellen of hangt af van de waarde van het interactief element.

- Take

Neem een selectie van $n$ elementen binnen het gefilterde resultaat. Er zijn twee manier om items te nemen, FIRST en RANDOM. FIRST neemt de eerst $n$ elementen in de lijst, en RANDOM neemt een willekeurige $n$ elementen. Net als skip is $n$ is handmatig in te stellen of hangt af van de waarde van het interactief element.

Acties

Met acties is het mogelijk objecten toe te voegen, verwijderen, balanceren en attributen aan te passen

- Factor

Herschaal de value van het interactief element van 0-100 naar een zelf ingestelde min-max range, en zet een geselecteerd attribuut naar deze waarde. Een factor gaat er altijd van uit dat de waarde van het interactieve element tussen 0 en 100 ligt. Deze houdt zich dus niet aan de grootte van een slider o.i.d.

- Change Attribute

Pas de waarde van een attribuutveld aan. Dit kan met meerdere operators:

• SET: overschrijf het attribuut met de nieuwe value
• ADD, SUBTRACT, MULTIPLY EN DIVIDE: combineer de bestaande attribute value en de nieuwe value

De nieuwe value kan handmatig ingesteld zijn of de value zijn van het interactief element.

- Attribute Noise

Voeg willekeurige ruis toe aan de attributen van de geselecteerde objecten. Er zijn drie typen ruis beschikbaar:

• UNIFORM: uniforme verdeling tussen min_value en max_value
• NORMAL: een normaalverdeling met gemiddelde mean en variantie sigma
• TRIANGLE: een driehoeksverdeling met minimum min_value, piek mean en maximum max_value

Voor elk attribuut wordt een trekking gemaakt van de geselecteerde verdeling, en hiervan wordt de absolute waarde van de trekking bij het attribuut opgeteld.

- Remove

Verwijdert objecten in de gefilterde lijst. Bevat drie modi:

• REMOVE ALL: verwijder alle objecten
• REMOVE N: verwijder $n$ objecten
• KEEP N: verwijder alles behalve $n$ objecten

$n$ is op het moment altijd de waarde van het interactieve element. Om een constant aantal elementen te verwijderen kan je met de TAKE filter-subselectie een handmatig ingesteld aantal objecten selecteren, en dan vervolgens combineren met een REMOVE ALL.

De REMOVE N en KEEP N stappen verwijderen altijd de voorste objecten in de gefilterde lijst eerst.

- Add

Voeg voor $n$ objecten die nog niet een child object van het zelfde type onder zich hebben hangen in de gefilterde lijst één child object per parent toe. Het object wat wordt toegevoegd moet gedefinieerd zijn als een "template" object. $n$ hangt af van de waarde van het interactieve element.

Als toelichting, stel we filteren op HouseGridConnection om $4$ ElectricHeatConversionAssets toe te voegen. In het scenario zitten al $2$ HouseGridConnections met een ElectricHeatConversionAsset. Na het uitvoeren van de add zijn er $6$ HouseGridConnections met een ElectricHeatConversionAsset.

- Set Count

Werkt hetzelfde als add, maar zet het aantal child objects van hetzelfde type onder de gefilterde objecten naar een precies aantal.

Als toelichting weer hetzelfde voorbeeld, stel we filteren op HouseGridConnection het aantal ElectricHeatConversionAssets naar $4$ te zetten. In het scenario zitten al $2$ HouseGridConnections met een ElectricHeatConversionAsset. Na het uitvoeren van de set_count zijn er $4$ HouseGridConnections met een ElectricHeatConversionAsset.

- BalanceGroup

Balanceer de onderliggende child models van een lijst gefilterde objecten. In de BalanceGroup geef je een lijst van template objecten mee, die onder de gefilterde objecten moeten komen te hangen. Ook hier gaan we uit van één child object per parent (parent in de gefilterde lijst). Van één van de types in de lijst van template objecten wordt het aantal naar de waarde gezet van het interactive element. Welk van de template objecten dit is is in te stellen met de parameter "selected model type name". Vervolgens worden de rest van de objecten gebalanceerd zodat er in totaal even veel child items waren als voorheen.

Als voorbeeld, stel we hebben weer een set HouseGridConnections 🏠 met verschillende types heating assets (🔥, ⚡) die we willen balanceren.

Het scenario is zo ingesteld:

GC:     🏠🏠🏠🏠🏠🏠🏠🏠
Assets: ⚡⚡🔥🔥🔥 🔥🔥🔥

Als we meer ⚡ willen, dan stellen we een balance rule in: als templates geven we 🔥 en ⚡ mee, en als selected model type name geven we het type van ⚡ mee. Het filter is ingesteld op HouseGridConnection, omdat we hieronder de assets willen balance. Wanneer de slider waar deze rule aan hangt op bijv. $5$ wordt gezet, dan wordt het aantal ⚡ naar $5$ gezet onder de HouseGridConnections, en omdat er in totaal $8$ huizen zijn wordt het aantal 🔥 naar $3$ gezet:

GC:     🏠🏠🏠🏠🏠🏠🏠🏠
Assets: ⚡⚡⚡⚡⚡🔥🔥🔥

- Add multiple under each parent

Voeg $n$ child objects toe onder elk van de objecten in het filter. Het object wat moet worden toegevoegd wordt meegegeven als een template object. Voorbeeld:

🏠🏠🏠  -> add 2 🚗 under each parent -> 🏠🏠🏠
🚗🚗                                     🚗🚗🚗
                                          🚗🚗🚗
                                          🚗🚗

Scenario JSON uitlezen

Het controleren van de uitvoering van regels vereist het lezen van JSON-gegevens van het holon endpoint. Het endpoint geeft naast de kosten ook het bewerkte scenario terug. Alleen op lokale omgevingen en de acceptatie omgeving wordt het scenario teogevoegd aan het resultaat. In de volgende stappen wordt uitgelegd hoe je JSON-gegevens kunt uitlezen.

1. Maak een request naar het /holon/ endpoint. Dit kan door naar bijvoorbeeld naar een casus te gaan en een slider te bewegen.

2. Kijk naar het resultaat van het request om de JSON-gegevens te vinden. Klik op de webpagina op F12, ga naar het network tablad, klik op het laatste /holon/ request en als laatst klik op Response. Het kan zijn dat je een slider opnieuw moet bewegen zodat er een nieuwe request gedaan wordt. Voor lokaal gebruik is dit request http://localhost:8000/wt/api/nextjs/v2/holon/

3. De JSON van het bewerkte scenario zoals die naar Anylogic wordt gestuurd, staat in de return body onder "scenario".

Attributen en subklasse overzicht

Alle model attributen en subklassen voor het instellen van scenario regels voor interactieve elementen kunnen op de volgende pagina gevonden worden:

http://holontool.nl/wt/cms/modelconfig/schema

Per hoofdklasse is te zien welke subklassen eronder vallen. Voor elke klasse is te zien welke attributen deze heeft. Hier wordt dezelfde schrijfwijze aangehouden zoals het in het CMS ingevuld kan worden. Als een attribuut een relatie attribuut is, d.w.z. het verwijst naar een ander model, dan zal achter de naam het sluisteken (|) staan gevolgd door de klasse van de relatie.

Gekloonde scenario's opschonen

Mochten er door fouten gekloonde modellen achterblijven, dan kunnen deze automisch opgeschoond worden.

1. Ga naar het volgende endpoint: http://localhost:8000/wt/api/nextjs/v2/cleanup/
   Vervang hier http://localhost:8000 voor de url van de omgeving die opgeschoond moet worden. Gekloonde scenario's worden meteen opgeruimd nadat er naar het endpoint gegaan is.