# Harmonic Sequence Details

Notes:
* updated from [original version](https://hackmd.io/R1MLCP4sRxiNz1CUAWzKIg?view) after architecture proposal from FZAG in February 2024
* removed participants: "Equity Manager + Dashboards", "ANSP (FMP)"
* added participants "Cloud Integration Layer", "Consumer", "Database"
* merged:
* "TTMS Controller" and "TTMS Optimizer" to "Optimizer"
* "Airport (Actor)" and "Airport (data repository)" to "Airport"
note: "Airport (data repository)" is partially the new "Database"

## FZAG Architecture

## Lab Environment in Vienna

package "Virtual Server" {
    folder "Test Data" as folder
    database "\nPostgreSQL\n" as db
    [Orchestrator Simulator] as osim
    [Optimizer] as opt
    [Privacy Enginge] as pe
    [MPC #1] as mpc1
    [MPC #2] as mpc2
    [MPC #3] as mpc3
    
    folder <-right- osim
    db <-up- osim
    osim -> opt
    opt -> pe
    pe -down-> mpc1
    pe -> mpc2
    pe -> mpc3
    mpc1 <-> mpc2
    mpc2 <-> mpc3
    mpc3 <-> mpc1
}

**Description:** The lab environment in Vienna is hosted in a secure environment with restricted access to nominated project participants only. It can only be accessed from within Frequentis via SSH (port 22).

<details><summary><strong>Sequence Diagram</strong></summary>

IMPORTANT: outdated version! (requires sync iwth Activity Diagrams below)

@startuml

participant "AUs (flight\npreferences)" as au
participant "Airport" as airport
participant "NM B2B\n(Network Manager)" as nm
participant "Cloud\nIntegration Layer" as int
participant "Consumer" as consumer
participant "Orchestrator" as orchestrator
database "Database" as db
participant "Optimizer" as optimizer
autonumber

==Continuous Operation==
consumer -> int: subscribe
nm -> int: send ANSP constraints\n(based on ANSP inputs)
airport -> int: send constraints\n(a few times a day)
au -> int: send preferences\n(every few minutes)
orchestrator -> nm: issue network cherry pick regulation

group Active Regulation
orchestrator -> nm: update network cherry pick regulation
==Measure Simulation==
int -> nm: retrieve ATFCM measures list\n(periodic queries, every 2min?)\nrequest regulationListRequest (flow Services) - page 18
int -> consumer: forward ATFCM measures list
consumer -> orchestrator: forward ATFCM measures list
orchestrator -> orchestrator: check if list includes measure\nstarting with 'XSZH' and still active
orchestrator -> nm: request measure information
orchestrator -> nm: request: SimulationStartRequest (flow Services)
orchestrator -> nm: request simulated flight list for Traffic Volume
orchestrator -> orchestrator: record simulation data
orchestrator -> nm: stop simulation

group Iterative Optimization
==Prepare Optimization==

orchestrator -> nm: request flight list (not based on regulation)
orchestrator -> orchestrator: compute arrival slot list\n(based on measure info + flight list)
int -> consumer: send current preferences
consumer -> orchestrator: forward current preferences
orchestrator -> db: persist preferences
orchestrator <- db: retrieve historic data
orchestrator -> orchestrator: optionally, adjust weights for\nequity management

==TTA Optimization==
orchestrator -> optimizer: request optimization
optimizer -> optimizer: iterative optimization\n(optional use of\nPrivacy Engine)
orchestrator -> optimizer: request updates /\noptimization results
orchestrator -> db: store optimization results

==TTA Distribution==
orchestrator -> orchestrator: check KPIs and simulation results\nif TTA Optimizationis good enough?\n-> might re-run (for first optimization)\n2..n optimzations: compare with\nprevious solution
orchestrator -> nm: send TTA request
orchestrator -> nm: request new flight sequence
orchestrator -> db: store actual flight sequencen\nand difference to proposed\nTTA sequence

end

end

==Conclude Regulation==
orchestrator -> nm: end network cherry\npick regulation
@enduml

</details>

## Activity Diagrams

General Requirements:
* every step should log the relevant information and provide traceable data (store input & output data)

### TTMS Process

@startuml
|Network Management|
|Airport (TTMS)|
|Stakeholder|
|Airport (TTMS)|
start
repeat
  repeat
    :A1.1\ncheck for active NCP regulation;
|Network Management|
    :E1.2\nProvide ATFCM measures list;
|Airport (TTMS)|
  repeat while (A1.3\nIncludes relevant\nNCP regulation?\n) is (no)
  -> yes;
  :A1.4\nRequest NCP measure details;
|Network Management|
  :E1.5\nProvide details for\nrequested measure;
|Airport (TTMS)|
  split
    :A1.6\nrequest CASA simulation;
|Network Management|
    :E1.7\nProvide results of the\nstandard CASA regulation\nsimulation;
|Airport (TTMS)|
    :A1.8\nStore results and stop\nCASA simulation;
  split again
    split
|Airport (TTMS)|
      :A1.9\nrequest flight list;
|Network Management|
      :E1.10\nprovide flight list; 
|Airport (TTMS)|
      :A1.11\nrequest current\nstakeholder preferences;
|Stakeholder|
      :S1.12\nprovide current preferences\n(continuously updated\nby airport & AUs);
|Airport (TTMS)|
    split again
      :A1.13\ncompute arrival\nsequence list;
    end split
|Airport (TTMS)|   
    :A1.14\nCreate weight maps\nincl. inequity weights;
    :A1.15\nOptimize arrivals;
  end split
  :A1.16\nCheck NCP regulation status;
|Network Management|
  :E1.17\nReturn NCP regulation status;
|Airport (TTMS)|
  if (A1.18\nNCP regulation cancelled?\n) then (yes)
      :A1.19\nsend requests to\nwithdraw TTAs;
|Network Management|
      :E1.20\nprocess cancellation\nof TTAs;
|Airport (TTMS)|
  else (no)
    if (A1.21\nNCP regulation is\nstill active and with\nno details changed? ) then (yes)
      if (A1.22\nResults better than simulation\nand surpass KPIs?\n) then (yes)
        :A1.23\nupdate NCP regulation\nwith TTA request;
|Network Management|
        :E1.24\nprocess NCP\nregulation updates;
|Airport (TTMS)|
        :A1.25\nStore TTA update response;
      else (no)
      endif
    else (no)
    endif
  endif
|Airport (TTMS)|
  repeat while (A1.26\ncontinous operation\n) is (continue)
  -> end process;
stop
@enduml

#### Required Updates:
* FMP position needs to review TTA updates before submission to NM
* FMP position needs to be informed in case a TTA update does not pass the KPI evaluation
* in case the Optimizer does not provide a result within a predefined time, FMP will issue a normal regulation

### TTMS Process - February 2025

@startuml
|Regional ATFCM\n(EUROCONTROL)|
|                      Airport\n(Target Time Management Solution)|
| Civil AU Operations\nCentre (Stakeholder)|
|                      Airport\n(Target Time Management Solution)|
start
repeat
  repeat
    :A1.1\ncheck for active NCP regulation;
|Regional ATFCM\n(EUROCONTROL)|
    :E1.2\nprovide NCP Regulation information\n(ATFCM measures list);
|                      Airport\n(Target Time Management Solution)|
  repeat while (A1.3\nincludes relevant\nNCP regulation?\n) is (no)
  -> yes;
  split
    :A1.6\nrequest CASA simulation;
|Regional ATFCM\n(EUROCONTROL)|
    :E1.7\nprovide results of the\nstandard CASA regulation\nsimulation;
|                      Airport\n(Target Time Management Solution)|
    :A1.8\nstop CASA simulation;
  split again
    split
      :A1.13\nuse arrival\nsequence list;
    split again
      :A1.11\nrequest current\nstakeholder preferences;
| Civil AU Operations\nCentre (Stakeholder)|
      :S1.12\nprovide current preferences\n(continuously updated\nby airport & AUs);
|                      Airport\n(Target Time Management Solution)|   
    end split
    :A1.14\ncreate weight maps\nincl. inequity weights;
    :A1.15\noptimize arrival sequence;
  end split
  if (A1.21\nNCP regulation is\nstill active and with\nno details changed? ) then (yes)
    if (A1.22\nwithin Safeguards?\n(validate results)\n) then (yes)
      :A1.23\nupdate NCP regulation\nwith TTA request;
|Regional ATFCM\n(EUROCONTROL)|
      :E1.24\nprocess NCP\nregulation updates;
|                      Airport\n(Target Time Management Solution)|
    else (end TTMS process)
      stop
    endif
  endif
|                      Airport\n(Target Time Management Solution)|
  repeat while (A1.26\ncontinous operation\n) is (continue)
  -> end TTMS process;
stop
@enduml

### FMP Airspace Monitoring Process

@startuml
|ANSP (FMP)|
|EUROCONTROL|
|ANSP (FMP)|
start
repeat
  :F2.1\nmonitor traffic count;
  split
  split again
    if (F2.2\nrequest Cherry\nPick Regulation\n) then (yes)
|EUROCONTROL|
      :E2.3\nactivate Cherry Pick Regulation;
|ANSP (FMP)|
    else (no)
    endif
  split again
    if (F2.4\ncancel Cherry\nPick Regulation\n) then (yes)
|EUROCONTROL|
      :E2.5\ndeactivate Network\nCherry Pick Regulation;
|ANSP (FMP)|
    else (no)
    endif
  end split
repeat while (F2.6\ncontinuous operation\n)
-> ;
stop
@enduml

### Recording of Flight Data Process (for Equity Managmenet)
*Note:* assumption is that all current flights are available via ZRH bridge - correct?
Relevant data for each flight:
* actual landing time
* last TTA sent
* scheduled time

@startuml
|EUROCONTROL|
|Airport (TTMS)|
start
repeat
  :A3.1\nrequest actual\nflight data for\nall current flights;
|EUROCONTROL|
  :E3.2\nprovide flight data;
|Airport (TTMS)|
repeat while (A3.3\nstore data &\nwait 5min\n)
-> ;
stop
@enduml

## KPIs
Hard constraints for Optimizer:
* Respecting given capacities
* do not arrive before STA +/- Δ, (Δ configurable when invoking the Optimizer)
* do not depart before earliestTimeOfDeparture
* Generated AFTCM delay shall be lower or same, than the recorded simulated CASA regulation's ATFCM delay

TTMS shall determine a TTA Sequence considering the following optimization criteria, which can be weighted among each other.
* Reduce wished-TTA Offset AUs
* Reduce wished-TTA Offset Airports
* Reduce Schedule Offset
* Reduce ATFM Delay

### Open Questions for KPI parameters
- [ ] where to retrieve capacities?
- [ ] how to map input data to capacity restrictions?
- [ ] map STA to Optimizer [Optimizer Input](https://hackmd.io/O0LnSKElSgeLm8GHZ8rA8g?view#Optimizer-Input)
- [ ] map earliestTimeOfDeparture to input Optimizer Input
- [ ] how to calculate ATFCM delay for an [Optimization Solution](https://hackmd.io/O0LnSKElSgeLm8GHZ8rA8g?view#OptimizerOutput)
- [ ] how to calculate ATFM delay