Differences

This shows you the differences between two versions of the page.

--- ports [2026/07/09 07:11]
hermann
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Ports ======
-A **port** is a typed connection point on a functor. Input ports receive data; output ports produce it. Every functor defines a fixed set of ports — their names, types, and whether they are required or optional — and data flows between functors by connecting an output port of one to an input port of another.
-===== Input Ports =====
-==== Required and optional inputs ====
-Every input port is either **required** or **optional**:
-  * **Required** ports must always be supplied — either by connecting an output from another functor or by providing a constant value directly. A model cannot run if a required input is missing.
-  * **Optional** ports have a **default value** that is used automatically when the port is not connected and no constant is provided. The default is specific to each port and is shown in the functor's documentation.
-==== Nullable inputs ====
-Some optional ports are also **nullable** — they explicitly accept the absence of a value as meaningful input. A nullable port whose default is already ''none'' can be left without a value intentionally by supplying the constant ''.none''. This is distinct from simply omitting the port (which uses the default) because it explicitly signals that no value is being provided.
-==== Editable inputs ====
-An **editable** port can receive a constant value typed directly into the GUI or written as a constant in an EGO Script call. Non-editable ports must be connected to an output from another functor; they cannot be supplied with a constant.
-==== Auto-bound inputs and outputs ====
-Some ports are **auto-bound** — when the functor is placed inside a compatible container, the port automatically connects to the relevant internal port of that container without needing an explicit connection. Auto-binding applies to both input and output ports.
-**Auto-bound input ports** connect automatically to an internal output of the enclosing container:
-  * **''step''** — on [[Step]], all ''Load*'' and ''Save*'' file I/O functors, and all ''Select*'' functors. Auto-binds to the ''step'' internal output of the enclosing loop container ([[Repeat]], [[For]], [[For Each]], [[For Each Category]], [[For Each Region]], [[While]], [[Do While]]).
-  * **''workdir''** — on all ''Load*'' and ''Save*'' file I/O functors. Auto-binds to the ''workdir'' internal output of the enclosing [[Workdir]] container.
-  * **''regionManager''** — on [[Get All Regions Info]], [[Get Region Info]], [[Region]], [[Region Manager Value]], [[Regional Map]], [[Regional Categorical Map]], [[Regionalize Map]], [[Regionalize Categorical Map]], [[Merge Regional Maps]], [[Merge Regional Categorical Maps]]. Auto-binds to the ''regionManager'' internal output of the enclosing [[Region Manager]], [[Region]], or [[For Each Region]] container.
-  * **''regionId''** — on [[Get Region Info]], [[Region]], [[Regional Map]], [[Regional Categorical Map]], [[Regionalize Map]], [[Regionalize Categorical Map]]. Auto-binds to the ''regionId'' internal output of the enclosing [[Region]] container.
-  * **''tableManager''** — on [[Merge Sub Tables]], [[Sub Table]], [[Table Manager Value]]. Auto-binds to the ''tableManager'' internal output of the enclosing [[Table Manager]] container.
-  * **''currentIndividual''** — on [[Get Current Individual]]. Auto-binds to the ''currentIndividual'' internal output of the enclosing [[Genetic Algorithm Tool]] container.
-**Auto-bound output ports** connect automatically to an internal input of the enclosing container:
-  * **''condition''** — on [[Set While Condition]]. Auto-binds to the ''condition'' internal input of the enclosing [[While]] or [[Do While]] container.
-  * **''fitness''** — on [[Set Fitness]]. Auto-binds to the ''fitness'' internal input of the enclosing [[Genetic Algorithm Tool]] container.
-===== Output Ports =====
-A functor may produce one or more outputs. In EGO Script, outputs are bound to variables using the '':='' operator. When a functor produces multiple outputs and only some are needed, the underscore ''_'' discards unwanted ones:
-<code>
-// Bind all outputs
-{ areaTable = areas } := CalcAreas { source = landscape };
-// Bind only the first output; discard the rest
-result := SomeFunctor input1 input2;
-// Discard first output; keep second
-_ secondOutput := SomeFunctor input1 input2;
-</code>
-===== Port Naming =====
-Port names follow different conventions depending on context:
-  * **In EGO Script**, port names are written in camelCase with a lowercase first letter: ''cellType'', ''resultIsSparse'', ''nullValue''.
-  * **In the GUI**, the same ports are displayed with spaces between words and all words capitalised: "Cell Type", "Result Is Sparse", "Null Value".
-The conversion between the two follows the same rules as [[ego_script#alias_and_variable_name_conversion|alias and variable name conversion]] in EGO Script.
-===== Port Types =====
-Every port has a **type** that determines what data it can carry. A port accepts data of its exact type or any type that can be automatically converted to it. See the [[type_system|type system]] documentation for the full list of types and their conversions.
-Two special constants are available for any input port regardless of type:
-  * ''.UNBOUND'' — the port is not connected, or its connection is deliberately being ignored. Used especially when copying a fragment of a model to a text editor, where some connections may not be part of the selection.
-  * ''.none'' — the port is intentionally left without a value. Valid **only for optional nullable input ports**.
-===== Sequence Ports =====
-Most container functors expose two special sequencing ports:
-  * ''sequenceInput'' — connecting a value here ensures the functor that produced that value completes before this container starts. Accepts any data type.
-  * ''sequenceOutput'' — pass this to another functor's ''sequenceInput'' to force this container to complete first.
-These ports carry no data; their only purpose is to impose execution ordering. See [[ego_script#sequence_ports|Sequence ports]] in the EGO Script documentation for details and examples.
-===== Internal Ports (Container Functors) =====
-Container functors communicate with the functors inside them through **internal ports**:
-  * **Internal output ports** carry values FROM the container INTO the contained functors. In EGO Script these are bound as the first declarations inside the container block using the ''{ variable = portName }'' form.
-  * **Internal input ports** carry values FROM the contained functors BACK TO the container. These are set by dedicated functors placed inside the block (such as [[Set While Condition]] for the ''condition'' port of a loop).
-==== Internal outputs by container ====
-^ Container ^ Internal output port ^ Type ^ Description ^
-| [[Do While]] | ''step'' | NonNegativeIntegerValue | Current iteration index, starting at 0. |
-| [[For]] | ''step'' | RealValue | Current value in the numeric range being iterated. |
-| [[For Each]] | ''step'' | RealValue | Current row value from the table being iterated. |
-| [[For Each Category]] | ''step'' | IntegerValue | Current category code from the categorical map. |
-| [[For Each Region]] | ''step'' | IntegerValue | Current region identifier. |
-| [[For Each Region]] | ''regionManager'' | RegionManager | The region manager for the current region. |
-| [[Repeat]] | ''step'' | NonNegativeIntegerValue | Current iteration index, starting at 0. |
-| [[While]] | ''step'' | NonNegativeIntegerValue | Current iteration index, starting at 0. |
-| [[Region Manager]] | ''regionManager'' | RegionManager | The region manager for the current region context. |
-| [[Region]] | ''regionManager'' | RegionManager | The region manager. |
-| [[Region]] | ''regionId'' | IntegerValue | The current region identifier. |
-| [[Workdir]] | ''workdir'' | Workdir | The working directory defined by the container. |
-| [[Table Manager]] | ''tableManager'' | TableManager | The table manager defined by the container. |
-| [[Genetic Algorithm Tool]] | ''currentIndividual'' | LookupTableGroup | The current individual in the genetic algorithm population. |
-==== Internal inputs by container ====
-^ Container ^ Internal input port ^ Type ^ Set by ^
-| [[While]] | ''condition'' | BooleanValue | [[Set While Condition]] — the ''condition'' output port is **auto-bound** to this internal input. |
-| [[Do While]] | ''condition'' | BooleanValue | [[Set While Condition]] — the ''condition'' output port is **auto-bound** to this internal input. |
-| [[Genetic Algorithm Tool]] | ''fitness'' | RealValue | [[Set Fitness]] — the ''fitness'' output port is **auto-bound** to this internal input. |
-See [[ego_script#internal_output_ports|Internal output ports]] and [[ego_script#internal_input_ports|Internal input ports]] for EGO Script syntax details and examples.
-===== Hook Ports (Calculator Functors) =====
-The five [[calculate_functors|calculator functors]] ([[Calculate Map]], [[Calculate Categorical Map]], [[Calculate Value]], [[Calculate Lookup Table Values]], [[Calculate Lookup Table Keys And Values]]) connect their data inputs through **hook** functors rather than directly:
-  * [[Number Map]] ports — connect raster maps; referenced in expressions as ''i1'', ''i2'', …
-  * [[Number Table]] ports — connect tables and lookup tables; referenced as ''t1'', ''t2'', …
-  * [[Number Value]] ports — connect scalar values; referenced as ''v1'', ''v2'', …
-In the abbreviated (shorthand) syntax, hook ports are implicit — operands are referenced directly by variable name using a type sigil (''#'' for maps, ''%'' for tables, ''$'' for values). See [[ego_script#calculator_functor_shorthand|Calculator functor shorthand]] for details.