1 /****************************************************************************/
2 // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.org/sumo
3 // Copyright (C) 2001-2019 German Aerospace Center (DLR) and others.
4 // This program and the accompanying materials
5 // are made available under the terms of the Eclipse Public License v2.0
6 // which accompanies this distribution, and is available at
7 // http://www.eclipse.org/legal/epl-v20.html
8 // SPDX-License-Identifier: EPL-2.0
9 /****************************************************************************/
10 /// @file    MSTrafficLightLogic.h
11 /// @author  Daniel Krajzewicz
12 /// @author  Eric Nicolay
13 /// @author  Jakob Erdmann
14 /// @author  Michael Behrisch
15 /// @author  Friedemann Wesner
16 /// @date    Sept 2002
17 /// @version $Id$
18 ///
19 // The parent class for traffic light logics
20 /****************************************************************************/
21 #ifndef MSTrafficLightLogic_h
22 #define MSTrafficLightLogic_h
23 
24 
25 // ===========================================================================
26 // included modules
27 // ===========================================================================
28 #include <config.h>
29 
30 #include <map>
31 #include <string>
32 #include <bitset>
33 #include <utils/common/Command.h>
34 #include <utils/common/Parameterised.h>
35 #include <microsim/MSLogicJunction.h>
36 #include <microsim/MSLink.h>
37 #include "MSPhaseDefinition.h"
38 
39 
40 // ===========================================================================
41 // class declarations
42 // ===========================================================================
43 class MSNet;
44 class MSLink;
45 class MSTLLogicControl;
46 class NLDetectorBuilder;
47 
48 
49 // ===========================================================================
50 // class definitions
51 // ===========================================================================
52 /**
53  * @class MSTrafficLightLogic
54  * @brief The parent class for traffic light logics
55  */
56 class MSTrafficLightLogic : public Named, public Parameterised {
57 public:
58     /// @name Structure definitions
59     /// @{
60 
61     /// @brief Definition of a list of phases, being the junction logic
62     typedef std::vector<MSPhaseDefinition*> Phases;
63 
64     /// @brief Definition of the list of links that are subjected to this tls
65     typedef std::vector<MSLink*> LinkVector;
66 
67     /// @brief Definition of a list that holds lists of links that do have the same attribute
68     typedef std::vector<LinkVector> LinkVectorVector;
69 
70     /// @brief Definition of the list of arrival lanes subjected to this tls
71     typedef std::vector<MSLane*> LaneVector;
72 
73     /// @brief Definition of a list that holds lists of lanes that do have the same attribute
74     typedef std::vector<LaneVector> LaneVectorVector;
75     /// @}
76 
77 
78 public:
79     /** @brief Constructor
80      * @param[in] tlcontrol The tls control responsible for this tls
81      * @param[in] id This tls' id
82      * @param[in] programID This tls' sub-id (program id)
83      * @param[in] logicType This tls' type (static, actuated etc.)
84      * @param[in] delay The time to wait before the first switch
85      * @param[in] parameters Additional parameters (especially for actuated logics)
86      */
87     MSTrafficLightLogic(MSTLLogicControl& tlcontrol,
88                         const std::string& id,
89                         const std::string& programID,
90                         const TrafficLightType logicType,
91                         const SUMOTime delay,
92                         const std::map<std::string, std::string>& parameters);
93 
94 
95     /** @brief Initialises the tls with information about incoming lanes
96      * @param[in] nb The detector builder
97      * @param[in] edgeContinuations Information about edge predecessors/successors
98      * @exception ProcessError If something fails on initialisation
99      */
100     virtual void init(NLDetectorBuilder& nb);
101 
102 
103     /// @brief Destructor
104     virtual ~MSTrafficLightLogic();
105 
106 
107 
108     /// @name Handling of controlled links
109     /// @{
110 
111     /** @brief Adds a link on building
112      * @param[in] link The controlled link
113      * @param[in] lane The lane this link starts at
114      * @param[in] pos The link's index (signal group) within this program
115      */
116     virtual void addLink(MSLink* link, MSLane* lane, int pos);
117 
118     /// @brief ignore pedestrian crossing index in mesosim
119     void ignoreLinkIndex(int pos);
120 
121 
122     /** @brief Applies information about controlled links and lanes from the given logic
123      *
124      * If we load a logic after the network has been loaded, we do not get the information
125      *  about controlled links afterwards. We have to copy them from a previously loaded logic.
126      *
127      * @param[in] logic The logic to use the information about controlled links/lanes from
128      */
129     virtual void adaptLinkInformationFrom(const MSTrafficLightLogic& logic);
130 
131 
132     /** @brief Returns the (uncontrolled) states of the controlled links
133      * @return The controlled link's states
134      */
135     std::map<MSLink*, LinkState> collectLinkStates() const;
136 
137 
138     /** @brief Resets the states of controlled links
139      * @param[in] vals The state of controlled links to use
140      */
141     void resetLinkStates(const std::map<MSLink*, LinkState>& vals) const;
142     /// @}
143 
144 
145 
146     /// @name Switching and setting current rows
147     /// @{
148 
149     /** @brief Switches to the next phase
150      * @return The time of the next switch
151      */
152     virtual SUMOTime trySwitch() = 0;
153 
154 
155     /** @brief Applies the current signal states to controlled links
156      * @param[in] t The current time
157      * @return Always true
158      * @see LinkState
159      * @see MSLink::setTLState
160      */
161     bool setTrafficLightSignals(SUMOTime t) const;
162     /// @}
163 
164 
165 
166     /// @name Static Information Retrieval
167     /// @{
168 
169     /** @brief Returns this tl-logic's id
170      * @return This program's id
171      */
getProgramID()172     const std::string& getProgramID() const {
173         return myProgramID;
174     }
175 
176 
177     /** @brief Returns the list of lists of all lanes controlled by this tls
178      * @return All lanes controlled by this tls, sorted by the signal index
179      */
getLaneVectors()180     const LaneVectorVector& getLaneVectors() const {
181         return myLanes;
182     }
183 
184 
185     /** @brief Returns the list of lanes that are controlled by the signals at the given position
186      * @param[in] i The index of the signal
187      * @return The lanes controlled by the signal at the given index
188      */
getLanesAt(int i)189     const LaneVector& getLanesAt(int i) const {
190         if (i < (int)myLanes.size()) {
191             return myLanes[i];
192         } else {
193             return myEmptyLaneVector;
194         }
195     }
196 
197 
198     /** @brief Returns the list of lists of all affected links
199      * @return All links controlled by this tls, sorted by the signal index
200      */
getLinks()201     const LinkVectorVector& getLinks() const {
202         return myLinks;
203     }
204 
205 
206     /** @brief Returns the list of links that are controlled by the signals at the given position
207      * @param[in] i The index of the signal
208      * @return The links controlled by the signal at the given index
209      */
getLinksAt(int i)210     const LinkVector& getLinksAt(int i) const {
211         return myLinks[i];
212     }
213 
214 
215     /** @brief Returns the index of the given link
216      * @param[in] link The link to retrieve the index for
217      * @return The index of the given link (-1 if it is not controlled by this tls)
218      */
219     int getLinkIndex(const MSLink* const link) const;
220 
221 
222     /** @brief Returns the number of phases
223      * @return The number of this tls program's phases
224      */
225     virtual int getPhaseNumber() const = 0;
226 
227 
228     /** @brief Returns the phases of this tls program
229      * @return The phases of this tls program
230      */
231     virtual const Phases& getPhases() const = 0;
232 
233 
234     /** @brief Returns the definition of the phase from the given position within the plan
235      * @param[in] givenstep The index of the phase within the plan
236      * @return The definition of the phase at the given position
237      */
238     virtual const MSPhaseDefinition& getPhase(int givenstep) const = 0;
239 
240     /** @brief Returns the type of the logic
241      * @return The type of the logic
242      */
getLogicType()243     TrafficLightType getLogicType() const {
244         return myLogicType;
245     }
246     /// @}
247 
248 
249 
250     /// @name Dynamic Information Retrieval
251     /// @{
252 
253     /** @brief Returns the current index within the program
254      * @return The index of the current phase within the tls
255      */
256     virtual int getCurrentPhaseIndex() const = 0;
257 
258 
259     /** @brief Returns the definition of the current phase
260      * @return The current phase
261      */
262     virtual const MSPhaseDefinition& getCurrentPhaseDef() const = 0;
263 
264 
265     /** @brief Returns the cycle time (in ms)
266      * @return The (maybe changing) cycle time of this tls
267      */
getDefaultCycleTime()268     SUMOTime getDefaultCycleTime() const {
269         return myDefaultCycleTime;
270     }
271 
272 
273     /** @brief Returns the assumed next switch time
274      *
275      * The time may change in case of adaptive/actuated traffic lights.
276      * @return The assumed next switch time (simulation time)
277      */
278     SUMOTime getNextSwitchTime() const;
279 
280 
281     /** @brief Returns the duration spent in the current phase
282      *
283      * @return The time spent in the current phase
284      */
285     SUMOTime getSpentDuration() const;
286     /// @}
287 
288 
289 
290     /// @name Conversion between time and phase
291     /// @{
292 
293     /** @brief Returns the index of the logic at the given simulation step
294      * @return The (estimated) index of the tls at the given simulation time step
295      */
296     virtual SUMOTime getPhaseIndexAtTime(SUMOTime simStep) const = 0;
297 
298 
299     /** @brief Returns the position (start of a phase during a cycle) from of a given step
300      * @param[in] index The index of the phase to return the begin of
301      * @return The begin time of the phase
302      */
303     virtual SUMOTime getOffsetFromIndex(int index) const = 0;
304 
305 
306     /** @brief Returns the step (the phasenumber) of a given position of the cycle
307      * @param[in] offset The offset (time) for which the according phase shall be returned
308      * @return The according phase
309      */
310     virtual int getIndexFromOffset(SUMOTime offset) const = 0;
311     /// @}
312 
313 
314 
315     /// @name Changing phases and phase durations
316     /// @{
317 
318     /** @brief Changes the duration of the next phase
319      * @param[in] duration The new duration
320      */
321     void addOverridingDuration(SUMOTime duration);
322 
323 
324     /** @brief Delays current phase by the given delay
325      * @param[in] delay The time by which the current phase shall be delayed
326      */
327     void setCurrentDurationIncrement(SUMOTime delay);
328 
329 
330     /** @brief Changes the current phase and her duration
331      * @param[in] tlcontrol The responsible traffic lights control
332      * @param[in] simStep The current simulation step
333      * @param[in] step Index of the phase to use
334      * @param[in] stepDuration The left duration of the phase
335      */
336     virtual void changeStepAndDuration(MSTLLogicControl& tlcontrol,
337                                        SUMOTime simStep, int step, SUMOTime stepDuration) = 0;
338 
339     /// @}
340 
341     /// @brief whether this logic is selected in the GUI
342     bool isSelected() const;
343 
344 protected:
345     /**
346      * @class SwitchCommand
347      * @brief Class realising the switch between the traffic light phases
348      */
349     class SwitchCommand : public Command {
350     public:
351         /** @brief Constructor
352          * @param[in] tlcontrol The responsible traffic lights control
353          * @param[in] tlLogic The controlled tls logic
354          * @param[in] duration Duration till next switch
355          */
356         SwitchCommand(MSTLLogicControl& tlcontrol,
357                       MSTrafficLightLogic* tlLogic,
358                       SUMOTime nextSwitch);
359 
360         /// @brief Destructor
361         ~SwitchCommand();
362 
363         /** @brief Executes the regarded junction's "trySwitch"- method
364          * @param[in] currentTime The current simulation time
365          * @return The time after which the command shall be executed again (the time of next switch)
366          */
367         SUMOTime execute(SUMOTime currentTime);
368 
369 
370         /** @brief Marks this swicth as invalid (if the phase duration has changed, f.e.)
371          * @param[in] tlLogic The controlled tls logic
372          */
373         void deschedule(MSTrafficLightLogic* tlLogic);
374 
375 
376         /** @brief Returns the assumed next switch time
377          * @return The assumed next switch time
378          */
getNextSwitchTime()379         SUMOTime getNextSwitchTime() const {
380             return myAssumedNextSwitch;
381         }
382 
383 
384     private:
385         /// @brief The responsible traffic lights control
386         MSTLLogicControl& myTLControl;
387 
388         /// @brief The logic to be executed on a switch
389         MSTrafficLightLogic* myTLLogic;
390 
391         /// @brief Assumed switch time (may change in case of adaptive traffic lights)
392         SUMOTime myAssumedNextSwitch;
393 
394         /// @brief Information whether this switch command is still valid
395         bool myAmValid;
396 
397     private:
398         /// @brief Invalidated copy constructor.
399         SwitchCommand(const SwitchCommand&);
400 
401         /// @brief Invalidated assignment operator.
402         SwitchCommand& operator=(const SwitchCommand&);
403 
404     };
405 
406 
407 protected:
408     /// @brief The id of the logic
409     const std::string myProgramID;
410 
411     /// @brief The type of the logic
412     const TrafficLightType myLogicType;
413 
414     /// @brief The list of LinkVectors; each vector contains the links that belong to the same link index
415     LinkVectorVector myLinks;
416 
417     /// @brief The list of LaneVectors; each vector contains the incoming lanes that belong to the same link index
418     LaneVectorVector myLanes;
419 
420     /// @brief A list of duration overrides
421     std::vector<SUMOTime> myOverridingTimes;
422 
423     /// @brief A value for enlarge the current duration
424     SUMOTime myCurrentDurationIncrement;
425 
426     /// @brief The current switch command
427     SwitchCommand* mySwitchCommand;
428 
429     /// @brief The cycle time (without changes)
430     SUMOTime myDefaultCycleTime;
431 
432     /// @brief An empty lane vector
433     static const LaneVector myEmptyLaneVector;
434 
435     /// @brief list of indices that are ignored in mesoscopic simulatino
436     std::set<int> myIgnoredIndices;
437 
438 private:
439     /// @brief initialize optional meso penalties
440     void initMesoTLSPenalties();
441 
442 
443 private:
444     /// @brief invalidated copy constructor
445     MSTrafficLightLogic(const MSTrafficLightLogic& s);
446 
447     /// @brief invalidated assignment operator
448     MSTrafficLightLogic& operator=(const MSTrafficLightLogic& s);
449 
450 };
451 
452 
453 #endif
454 
455 /****************************************************************************/
456 
457