// -*- C++ -*-
namespace Katabatic {
/*! \class AutoSegment
*
* \brief Abstract base class for AutoSegment
*
*
* \section secASCreation Creating AutoHorizontal & AutoVertical
*
* AutoSegment is the abstract base class for AutoHorizontal and
* AutoVertical. They are must be created only through the
* factory method: AutoSegment::create().
*
*
* \section secASCharacteristics Characteristics of AutoSegments
*
* <ul>
* <li>Unique ID: to ease the enforcing of a deterministic behavior
* and to gain some independance from the pointers, each AutoSegment
* is associated with an unique identifier.
* \red{<b>IDs</b> are now directly taken from the Hurricane::Segment.}
* <li>Source contact is always lesser than Target contact
* <code>(Xs,Ys) < (Xt,Yt)</code>.
* <li>When assembled through AutoContactVTee or AutoContactHTee,
* AutoSegments became (i.e. must be kept) aligneds. Among a
* set of aligned AutoSegments, we distinguish a representative
* trough which we can manipulate the whole set. This representative
* is called the \e canonical AutoSegment and is the one with the
* lowest \c id).
* <li>When an aligned set contains at least one global, all the segments
* of the set are tagged Katabatic::SegWeakGlobal. This is
* especially useful on local ones to know if they are part of a
* much longer wire.
*
* Conversely, a set of aligned may contains only local segments and
* thus will not have the flag set.
* <li>To allow some optimization, the Katabatic::SegNotAligned
* tells if a segment is part of an aligned set. It is deduced from
* the type of both source and target contact: not on the parallel
* branch of a tee.
* </ul>
*
* <b>The Ever Fragmenting Data Structure</b>
*
* All the transformations applied to the database, after it's initial
* building, can be reduced to making new doglegs (and layer changes).
* Another way to put it, is that no Tee is ever created after the
* initial stage. The consequence is that the segments are only fragmenting
* more and more (up to a certain limit). The aligneds sets are progessively
* broken apart as needed, and until there remains only one tee per set
* (the two segments on the aligned branch).
*
*
* \section secASOperations Operations on AutoSegments
*
* <ul>
* <li><b>Slackening.</b> Constraints transmited through either source
* or target AutoContact are too tight (tighter than the GCell),
* by adding straps in the perpandicular direction, the full slack
* of the segment is restored.
* <li><b>Layer Change.</b> One or two layers above or below the
* current layer. One up/down may means into the perpandicular
* routing direction.
* <li><b>Dogleg Creation.</b> Mean breaking the segment in two.
* This operation is used to slacken the constraints on a segment
* or restore connexity on source/target contact after a layer
* change. The new segment is always created on the source.
* <li><b>Reduction/Raising.</b> When a segment is a short dogleg,
* no greater than one picth, it can use the layer of the
* perpandiculars.
* </ul>
*
*
* \section secASInvalidate Invalidate on AutoSegments
*
* The simple invalidation of an AutoSegment <b>do not</b> invalidate
* it's source & target contact.
*
* An axis position change or a layer change both invalidate the
* AutoSegment <b>and</b> it's source & target contacts.
*
* For the complete invalidation/revalidation mechanism see
* \ref secSessionAlgo "Session Algorithm".
*
*
* \section secASAttributes Main Attributes of AutoSegments
*
* AutoSegment retains all attributes from Segment. The Segment itself
* beeing accessible through the base() methods.
* <ul>
* <li>An unique \c Id (for determinism).
* <li>The GCell from wich it starts from. It is the GCell of the
* source AutoContact.
* <li>A state, combination of flags from Katabatic::AutoSegmentFlag.
* <li>An interval for the optimal range of the AutoSegment axis.
* <li>An interval for user's defined constraint on the axis.
* <li>The interval giving the complete length of the AutoSegment,
* that is, with all extentions cap taken into account.
* This interval is refered as the \e span.
* <li>A small counter, of the number of reduced neighbors (never
* exceed two).
* </ul>
*
*
* \section secASImplementation Implementation Details
*
* AutoSegment / AutoHorizontal & AutoVertical are kind of decorators of
* Hurricane::Segment (they do not scrictly respect the pattern).
*
* Canonical AutoSegment can should be considered as a kind of Composite.
*
* Thoses objects are created using a Factory method.
*
*
* \section secASMethodsClassif Methods Classification
*
* <ul>
* <li><em>Wrapper methods</em> on the underlying Hurricane::Segment.
* </ul>
* <ul>
* <li><em>Atomic methods</em> on AutoSegment, that is, which applies exactly
* on the current AutoSegment.
* </ul>
* <ul>
* <li><em>Canonical methods</em> that applies on the set of aligned AutoSegments.
* There are two kind of those, the methods part of the API, and
* the ones that make the link with the atomic methods. Those
* intermediate methods hide some cumbersome AutoSegment list
* parameters.
* <ul>
* <li>AutoSegment::invalidate()
* <li>AutoSegment::computeOptimal()
* <li>AutoSegment::setAxis()
* <li>AutoSegment::toConstraintAxis()
* <li>AutoSegment::toOptimalAxis()
* </ul>
* </ul>
* <ul>
* <li><em>Uniform access</em>, to simplify the managment of AutoHorizontal
* and AutoVertical through AutoSegment, a set of uniformized methods is
* introduced. For instance, to avoid to check the dynamic type to choose
* to call getSourceX() or getSourceY(), we may call getSourceU().
* Uniform methods are named by replacing \c X/Y with \c U.
* <ul>
* <li>AutoSegment::getSourceU()
* <li>AutoSegment::getTargetU()
* <li>AutoSegment::getDuSource()
* <li>AutoSegment::getDuTarget()
* <li>AutoSegment::getSpanU()
* <li>AutoSegment::setDuSource()
* <li>AutoSegment::setDuTarget()
* </ul>
* </ul>
*/
//! \enum AutoSegmentFlag
//! Set of flags to describe the internal state of an AutoSegment.
//! \var AutoSegmentFlag::SegHorizontal
//! This AutoSegment is associated to a Hurricane::Horizontal, if not
//! set, it is associated to a Hurricane::Vertical. Set when the object
//! is constructed.
//! \var AutoSegmentFlag::SegFixed
//! The Hurricane::Segment associated must/cannot be moved.
//! \var AutoSegmentFlag::SegGlobal
//! The AutoSegment span between at least two GCells (i.e. not fully enclosed
//! in one).
//! \var AutoSegmentFlag::SegWeakGlobal
//! The AutoSegment is part of an aligned set which contains at least a global.
//! The global segment is itself tagged as weak global.
//! \var AutoSegmentFlag::SegCanonical
//! This AutoSegment is the designated representant of a set of aligned
//! AutoSegment.
//! \var AutoSegmentFlag::SegBipoint
//! This AutoSegment is a straight wire between two terminal AutoContact.
//! \var AutoSegmentFlag::SegDogleg
//! This AutoSegment has been created as the perpandicular part of a dogleg.
//! \var AutoSegmentFlag::SegStrap
//! This AutoSegment has been created to to reconnect parts of an AutoSegment
//! after slackening.
//! \var AutoSegmentFlag::SegSourceTop
//! The source contact of this segment is connected to the <em>top</em> layer.
//! \var AutoSegmentFlag::SegSourceBottom
//! The source contact of this segment is connected to the <em>bottom</em> layer.
//! \var AutoSegmentFlag::SegTargetTop
//! The target contact of this segment is connected to the <em>top</em> layer.
//! \var AutoSegmentFlag::SegTargetBottom
//! The target contact of this segment is connected to the <em>bottom</em> layer.
//! \var AutoSegmentFlag::SegIsReduced
//! This segment is the perpandicular part of a dogleg which will use the
//! <em>same</em> layer as the parallels.
//! \var AutoSegmentFlag::SegLayerChange
//! This AutoSegment has been created to to reconnect parts of an AutoSegment
//! after a layer change.
//! \var AutoSegmentFlag::SegSlackened
//! This AutoSegment has been slackened, that is freed from any constraints from
//! source or target through the insertion of straps.
//! \var AutoSegmentFlag::SegStrongTerminal
//! This AutoSegment directly connected to a terminal.
//! \var AutoSegmentFlag::SegWeakTerminal1
//! This AutoSegment indirectly connected to a terminal with medium strength.
//! \var AutoSegmentFlag::SegWeakTerminal2
//! This AutoSegment indirectly connected to a terminal with weak strength.
//! \var AutoSegmentFlag::SegNotSourceAligned
//! This source contact of the segment is not the aligned part of a tee
//! (\c h1 or \c h2 for a \c HTee, \c v1 or \c v2 for a \c VTee).
//!
//! \sa AutoSegmentFlag::SegNotAligned
//! \var AutoSegmentFlag::SegNotTargetAligned
//! This target contact of the segment is not the aligned part of a tee
//! (\c h1 or \c h2 for a \c HTee, \c v1 or \c v2 for a \c VTee).
//!
//! \sa AutoSegmentFlag::SegNotAligned
//! \var AutoSegmentFlag::SegAxisSet
//! This AutoSegment has been explicitly positionned at least once.
//! \var AutoSegmentFlag::SegInvalidated
//! This position or topology of this AutoSegment has been changed, needing
//! a revalidation.
//! \var AutoSegmentFlag::SegInvalidatedLayer
//! The segment has been chenged of layer, but the source & target AutoContact
//! have not been topologicaly checked yet. This flag \b must be used in
//! whith AutoSegmentFlag::SegInvalidated.
//! \var AutoSegmentFlag::SegCreated
//! The AutoSegment has just been created. This flag is set only from the
//! contruction of the object until is \e first revalidation. Used to
//! disable some tests that cannot be satisfied initially.
//! \var AutoSegmentFlag::SegWeakTerminal
//! A mask composed of:
//! - Katabatic::SegStrongTerminal
//! - Katabatic::SegWeakTerminal1
//! - Katabatic::SegWeakTerminal2
//! \var AutoSegmentFlag::SegNotAligned
//! A mask composed of:
//! - Katabatic::SegNotSourceAligned
//! - Katabatic::SegNotTargetAligned
//!
//! This mask is a quick way to know if a segment is \b not part of an aligned set.
//! It means that the segment is, on both ends, either connected to a terminal,
//! a turn <em>or the stem part of a tee</em>.
//! \function AutoSegment* AutoSegment::create ( AutoContact* source, AutoContact* target, Segment* hurricaneSegment );
//! \param source The source AutoContact.
//! \param target The target AutoContact.
//! \param hurricaneSegment The Hurricane::Segment to decorate.
//! \return The AutoHorizontal/AutoVertical decorator segment.
//!
//! Factory method to create AutoHorizontal or AutoVertical. It is important
//! to note that this function may modify the underlying Hurricane::Segment.
//! - Layer is set to the default (bottom) routing Layers.
//! - Source & target anchor of \c hurricaneSegment are set on \c source
//! and \c target. If the \c hurricaneSegment is already anchored and
//! \c source or \c target are not the one decorating the anchors, an
//! exception is thrown.
//! \function AutoSegment* AutoSegment::create ( AutoContact* source, AutoContact* target, unsigned int dir, size_t depth );
//! \param source The source AutoContact.
//! \param target The target AutoContact.
//! \param dir Specify the segment direction.
//! \param depth The layer, given by it's depth in the RoutingGauge.
//! \return The AutoHorizontal/AutoVertical.
//!
//! Factory method to create AutoHorizontal or AutoVertical.
//! \c flags indicate the direction (KbHorizontal or KbVertical).
//! The underlying Hurricane segment is also created.
//! \function Segment* AutoSegment::base() const;
//! \sreturn the decorated Hurricane::Segment (const flavor).
//! \function Segment* AutoSegment::base();
//! \sreturn the decorated Hurricane::Segment.
//! \function Horizontal* AutoSegment::getHorizontal();
//! \sreturn If the decorated segment is a Hurricane::Horizontal, return it.
//! \c NULL otherwise.
//! \function Vertical* AutoSegment::getVertical();
//! \sreturn If the decorated segment is a Hurricane::Vertical, return it.
//! \c NULL otherwise.
//! \function Cell* AutoSegment::getCell() const;
//! \see Segment::getCell().
//! \function Net* AutoSegment::getNet() const;
//! \see Segment::getNet().
//! \function const Layer* AutoSegment::getLayer() const;
//! \see Segment::getLayer().
//! \function BoundingBox* AutoSegment::getBoundingBox() const;
//! \see Segment::getBoundingBox().
//! \function Hook* AutoSegment::getSourceHook();
//! \see Segment::getSourceHook().
//! \function Hook* AutoSegment::getTargetHook();
//! \see Segment::getTargetHook().
//! \function Contact* AutoSegment::getSource() const;
//! \see Segment::getSource().
//! \function Contact* AutoSegment::getTarget() const;
//! \see Segment::getTarget().
//! \function Component* AutoSegment::getOppositeAnchor( Component* ) const;
//! \see Segment::getNet().
//! \function Components AutoSegment::getAnchors() const;
//! \see Segment::getAnchors().
//! \function DbU::Unit AutoSegment::getX() const;
//! \see Segment::getX().
//! \function DbU::Unit AutoSegment::getY() const;
//! \see Segment::getY().
//! \function DbU::Unit AutoSegment::getWidth() const;
//! \see Segment::getWidth().
//! \function DbU::Unit AutoSegment::getLength() const;
//! \see Segment::getLength().
//! \function DbU::Unit AutoSegment::getSourcePosition() const;
//! \see Segment::getSourcePosition().
//! \function DbU::Unit AutoSegment::getTargetPosition() const;
//! \see Segment::getTargetPosition().
//! \function DbU::Unit AutoSegment::getSourceX() const;
//! \see Segment::getSourceX().
//! \function DbU::Unit AutoSegment::getSourceY() const;
//! \see Segment::getSourceY().
//! \function DbU::Unit AutoSegment::getTargetX() const;
//! \see Segment::getTargetX().
//! \function DbU::Unit AutoSegment::getTargetY() const;
//! \see Segment::getTargetY().
//! \function DbU::Unit AutoSegment::invert();
//! \see Segment::invert().
//! \function void AutoSegment::setLayer( const Layer* );
//! \see Segment::setLayer().
//! \function bool AutoSegment::isHorizontal() const;
//! \sreturn \true if the Hurricane::Segment is Horizontal.
//! \function bool AutoSegment::isVertical() const;
//! \sreturn \true if the Hurricane::Segment is Vertical.
//! \function bool AutoSegment::isGlobal() const;
//! \sreturn \true if the segment is global (span over more than one GCell).
//! \function bool AutoSegment::isLocal() const;
//! \sreturn \true if the segment is local (fully enclosed in one GCell).
//! \function bool AutoSegment::isFixed() const;
//! \sreturn \true if segment must not be moved by the router.
//! \function bool AutoSegment::isBipoint() const;
//! \sreturn \true if the segment straigh join two terminals.
//! \function bool AutoSegment::isWeakTerminal() const;
//! \sreturn \true if segment is indirectly connected to a terminal.
//! \function bool AutoSegment::isStrongTerminal( unsigned int flags=0 ) const;
//! \sreturn \true if segment is directly connected to a terminal.
//! \function bool AutoSegment::isLayerChange() const;
//! \sreturn \true if segment is a strap used only to connect between two different
//! metal layers on the way up or down.
//! \function bool AutoSegment::isSpinTop() const;
//! \sreturn \true if segment is connected to turns and both perpandiculars segments
//! are in the \e top layer (candidate for reduction).
//! \function bool AutoSegment::isSpinBottom() const;
//! \sreturn \true if segment is connected to turns and both perpandiculars segments
//! are in the \e bottom layer (candidate for reduction).
//! \function bool AutoSegment::isSpinTopOrBottom() const;
//! \sreturn \true if segment is either <em>spin top</em> or <em>spin bottom</em>
//! (candidate for reduction).
//! \function bool AutoSegment::isReduced() const;
//! \sreturn \true if segment is actually in a reduced state: it's effective layer
//! will be the one of it's perpandiculars.
//! \function bool AutoSegment::isStrap() const;
//! \sreturn \true if segment has been created from a slackening operation to
//! restore the slack of another segment.
//! \function bool AutoSegment::isDogleg() const;
//! \sreturn \true if segment has been created as the perpandicular part of a dogleg.
//! \function bool AutoSegment::isInvalidated() const;
//! \sreturn \true if segment has been moved or topologicaly altered.
//! \function bool AutoSegment::isInvalidatedLayer() const;
//! \sreturn \true if segment has been changed of layer. Source and Target AutoContact
//! may need to be altered.
//! \function bool AutoSegment::isCreated() const;
//! \sreturn \true if segment has just been created and is not revalidated for the
//! first time
//! \function bool AutoSegment::isCanonical() const;
//! \sreturn \true if segment is the representant of an aligned set.
//! \function bool AutoSegment::isUnsetAxis() const;
//! \sreturn \true if the segment axis has never been set.
//! \function bool AutoSegment::isSlackened() const;
//! \sreturn \true if the segment has already been slackened.
//! \function unsigned int AutoSegment::canDogleg( Interval interval );
//! \sreturn non-zero if the aligned set of segment can be broken \e outside \c interval.
//! The returned value could be zero (failure) or Katabatic::KbDoglegOnLeft
//! or Katabatic::KbDoglegOnRight menaing that the aligned set could be broken
//! on the left of the \c interval (resp. right of it).
// \function bool AutoSegment::canDesalignate( AutoContact* contact ) const;
// \sreturn \true if \c contact restrict the slack of the segment.
//! \function bool AutoSegment::canReduce() const;
//! \sreturn \true if the segment can be reduced. That is:
//! - Source & target are AutoContactTurn.
//! - It is either <em>spin top</em> or <em>spin bottom</em>, that is
//! connecting perpandiculars both in the same layer.
//! - Has a length less or equal one pitch in the perpandicular direction.
//! - Neither of the perpandicular are also reduceds.
//! \function bool AutoSegment::mustRaise() const;
//! \sreturn \true if the segment must \e be reduced. That is:
//! - It is in reduced state...
//! - It is no longer <em>spin top</em> or <em>spin bottom</em>.
//! - It's length exceed one pitch in the perpandicular direction.
//! \function bool AutoSegment::canSlacken( unsigned int flags=0 ) const;
//! \sreturn \true if the segment can be slackened. That is, source or target constraints
//! are less than three pitches.
//!
//! If \c flags contains KbPropagate, look on the whole aligned set.
//! \function bool AutoSegment::_canSlacken() const;
//! \sreturn \true if the segment can be slackened. That is, source or target constraints
//! are less than three pitches.
//! \function bool AutoSegment::canMoveULeft( float reserve ) const;
//! \return \true if the \e global segment can be moved on the left GCell (for a
//! vertical) or down (for an horizontal). The move is accepted only if
//! it do not change the amount of global wiring. Thus the following
//! conditions:
//! - The segment mustn't be on the leftmost GCell (obvious...).
//! - The segment must be global.
//! - The source and target contacts must be AutoContactTurn(s).
//! - At least one of the perpandicular must be global \b and connected
//! through the \e target. That is, it's a global which extends toward
//! left.
//! - The GCell of maximum density on the left must remains below the
//! current GCell of maximum density, with a margin of \c reserve
//! (expressed in total saturation percentage).
//! \function bool AutoSegment::canMoveURight( float reserve ) const;
//! \return \true if the \e global segment can be moved on the right GCell (for a
//! vertical) or up (for an horizontal). The move is accepted only if
//! it do not change the amount of global wiring. Thus the following
//! conditions:
//! - The segment mustn't be on the leftmost GCell (obvious...).
//! - The segment must be global.
//! - The source and target contacts must be AutoContactTurn(s).
//! - At least one of the perpandicular must be global \b and connected
//! through the \e source. That is, it's a global which extends toward
//! right.
//! - The GCell of maximum density on the left must remains below the
//! current GCell of maximum density, with a margin of \c reserve
//! (expressed in total saturation percentage).
//! \function bool AutoSegment::canMoveUp( float reserve, unsigned int flags ) const;
//! \param reserve Number of track that must remains free \e after the move.
//! \param flags Modificate the method behavior, see below.
//! \return \true if the segment can be moved up, that is to the next layer above in
//! the same preferred routing direction. This method will check that in
//! every GCell of the segment, at least \c reserve tracks are still avalaible
//! \e after the segment has been moved up (\c reserve can be less than
//! \c 1.0).
//!
//! Possible (bitwise) value for \c flags :
//! - \c KbAllowTerminal : allow strong terminal to be moved up.
//! - \c KbAllowLocal : allow local segments to be moved up.
//! - \c KbPropagate : perform the check on the whole aligned set.
//! - \c KbWithPerpands : also check the density on the perpandiculars
//! begin & end GCell, there must be at least a \c 0.5 density
//! reserve on them.
//! \function bool AutoSegment::canPivotUp( float reserve, unsigned int flags ) const;
//! \param reserve Number of track that must remains free \e after the move.
//! \param flags Modificate the method behavior, see below.
//!
//! Checks of the segment can be \e pivoted up. The difference between
//! \c canMoveUp() and \c canPivotUp() lies in the fact that no
//! perpandicular segment needs to be altered if the current segment
//! is moved up. For example an \b M3 segment connected to only \b M4 can
//! be pivoted up (in \b M5), but if connected to \b M2, it cannot.
//!
//! Possible (bitwise) value for \c flags :
//! - \c KbPropagate : perform the check on the whole aligned set.
//! - \c KbIgnoreContacts : do not check the source & target layers
//! to know if the segment can be pivoted up.
//! \function bool AutoSegment::canPivotDown( float reserve, unsigned int flags ) const;
//! \param reserve Number of track that must remains free \e after the move.
//! \param flags Modificate the method behavior, see below.
//!
//! Checks of the segment can be \e pivoted down. The difference between
//! \c canMoveDown() and \c canPivotDown() lies in the fact that no
//! perpandicular segment needs to be altered if the current segment
//! is moved down.
//!
//! Possible (bitwise) value for \c flags :
//! - \c KbPropagate : perform the check on the whole aligned set.
//! \function bool AutoSegment::checkPositions() const;
//! \sreturn \true if the relative positions of source & target are coherent.
//! (source <= target).
//! \function bool AutoSegment::checkConstraints() const;
//! \sreturn \true if the constraint intervel is coherent (non-empty or
//! punctual in the worst case).
//! \function unsigned long AutoSegment::getId() const;
//! \sreturn The AutoSegment unique identifier.
//! \function unsigned int AutoSegment::getDirection() const;
//! \sreturn Katabatic::KbHorizontal or Katabatic::KbVertical according to the decorated segment.
//! \function GCell* AutoSegment::getGCell() const;
//! \sreturn The GCell into which the AutoSegment starts (the one of the source).
//! \function size_t AutoSegment::getGCells( vector<GCell*>& gcells ) const;
//! \param gcells A vector that will be filled by all the GCells that the
//! segment overlap. In increasing order, from source to target.
//! \return The vector's size.
//! \function AutoContact* AutoSegment::getAutoSource() const;
//! \sreturn The source AutoContact.
//! \function AutoContact* AutoSegment::getAutoTarget() const;
//! \sreturn The target AutoContact.
//! \function AutoContact* AutoSegment::getOppositeAnchor( AutoContact* contact ) const;
//! \sreturn The source or target AutoContact opposite to \c contact.
//! \function size_t AutoSegment::getPerpandicularsBound( set<AutoSegment*>& bounds );
//! \param bounds A vector that will be filled by all the AutoSegments perpandicular
//! to this one that induce a constraint.
//! \return The vector's size.
//! \function AutoSegment* AutoSegment::getParent() const;
//! \sreturn If this segment has been created by a dogleg operation, the parent is
//! the one from which we fragmented.
//! \function DbU::Unit AutoSegment::getAxis() const;
//! \sreturn The AutoSegment axis position.
//! \function DbU::Unit AutoSegment::getSourceU() const;
//! \sreturn The AutoSegment \e uniform source position. (X for an horizontal and
//! Y for a Vertical).
//! \function DbU::Unit AutoSegment::getTargetU() const;
//! \sreturn The AutoSegment \e uniform target position. (X for an horizontal and
//! Y for a Vertical).
//! \function DbU::Unit AutoSegment::getDuSource() const;
//! \sreturn The AutoSegment \e uniform delta from source. (dX for an horizontal and
//! dY for a Vertical).
//! \function DbU::Unit AutoSegment::getDuTarget() const;
//! \sreturn The AutoSegment \e uniform delta from source. (dX for an horizontal and
//! dY for a Vertical).
//! \function DbU::Unit AutoSegment::getOrigin() const;
//! \sreturn The AutoSegment \e uniform source (lowest) GCell coordinate. (dX for an horizontal and
//! dY for a Vertical).
//! \function DbU::Unit AutoSegment::getExtremity() const;
//! \sreturn The AutoSegment \e uniform target (greatest) GCell coordinate. (dX for an horizontal and
//! dY for a Vertical).
//! \function Interval AutoSegment::getSpanU() const;
//! \sreturn The AutoSegment \e uniform occupying interval (on X for horizontal and
//! on Y for vertical).
//! \function Interval AutoSegment::getSourceConstraints( unsigned int flags ) const;
//! \return The Interval into witch the source AutoContact can vary. By default
//! all deduced constraints and user constraints are took into account.
//! If \c flags contains \c KbNativeConstraints the constraint returned is
//! only the enclosing GCell.
//! \function Interval AutoSegment::getTargetConstraints( unsigned int flags ) const;
//! \return The Interval into witch the target AutoContact can vary. By default
//! all deduced constraints and user constraints are took into account.
//! If \c flags contains \c KbNativeConstraints the constraint returned is
//! only the enclosing GCell.
//! \function bool AutoSegment::getConstraints( DbU::Unit& min, DbU::Unit& max ) const;
//! \sreturn in \c min & \c max the allowed range for the segment axis.
//! \function bool AutoSegment::getConstraints( Interval& i ) const;
//! \sreturn in \c i the allowed range for the segment axis.
//! \function const Interval& AutoSegment::getUserConstraints() const;
//! \sreturn A reference to the additional constraints added to the axis of the segment.
//! \function DbU::Unit AutoSegment::getSlack() const;
//! \sreturn The length of the axis constraint interval.
//! \function DbU::Unit AutoSegment::getOptimalMin() const;
//! \sreturn The AutoSegment minimum axis optimal range.
//! \function DbU::Unit AutoSegment::getOptimalMax() const;
//! \sreturn The AutoSegment maximum axis optimal range.
//! \function Interval& AutoSegment::getOptimal( Interval& i ) const;
//! Inialize \c i with the AutoSegment axis optimal range.
//! \function DbU::Unit AutoSegment::getCost( DbU::Unit axis ) const;
//! \return The cost if this segment is placed at \c axis. The cost is null if
//! \c axis is inside the optimal interval and is the distance toward
//! the nearest bound outside.
//! \function AutoSegment* AutoSegment::getCanonical( Interval& i );
//! \return The canonical segment associated to this one. Additionnaly compute
//! the source & target position of the whole set of aligned segments.
//! \function AutoSegment* AutoSegment::getCanonical( DbU::Unit& min, DbU::Unit& max );
//! \return The canonical segment associated to this one. Additionnaly compute
//! the source & target position of the whole set of aligned segments.
//! \function unsigned int AutoSegment::_getFlags () const;
//! Sets \c flags given as arguments.
//! \function void AutoSegment::setFlags ( unsigned int flags );
//! Sets \c flags given as arguments.
//! \function void AutoSegment::unsetFlags ( unsigned int flags );
//! Unsets \c flags given as arguments.
//! \function void AutoSegment::setDuSource( DbU::Unit du );
//! Set the \e uniform \c dU from source anchor (dX for Horizontal,
//! dY for Vertical).
//! \function void AutoSegment::setDuTarget( DbU::Unit du );
//! Set the \e uniform \c dU from target anchor (dX for Horizontal,
//! dY for Vertical).
//! \function void AutoSegment::updateOrient ();
//! Ensure that source is lower than target. Swap them if needed.
//! Swap never occurs on global segment because their source and target
//! anchors are from different GCell, which are already ordered.
//! \function void AutoSegment::computeTerminal ();
//! Recompute the terminal status of an AutoSegment. Initially, a
//! segment which source or target is a terminal is flagged as
//! SegStrongTerminal. After a topological modification, if the
//! segment is no longer directly attached to a terminal, the
//! status is progessively weakened. Once it reaches the weakest
//! level, it stays on it so the algorithm can work out which
//! segments is a start to a path toward a terminal.
//!
//! Status from stronger to weaker:
//! - Katabatic::SegStrongTerminal.
//! - Katabatic::SegWeakTerminal1
//! - Katabatic::SegWeakTerminal2
//!
//! \remark The weakening is poorly done. After making a dogleg we do not
//! know which of the segment must be weakened if not directly attached
//! on a terminal. We must examinate source & target.
//! \function void AutoSegment::updatePositions();
//! Update the segment begenning and ending positions. The positions
//! takes into account the extension caps and reflect the real space
//! used by the segment under it's long axis.
//! \function void AutoSegment::mergeUserConstraints( const Interval& constraints );
//! Constraints applies on the valid axis interval.
//! Merge in \c constraints with the user's constraints. The resulting
//! constraints is the intersection of the former user's contraints and
//! the one given as argument.
//! \function void AutoSegment::resetUserConstraints();
//! Constraints applies on the valid axis interval.
//! Suppress all user's constraints.
//! \function void AutoSegment::setOptimalMin( DbU::Unit min );
//! Sets the lower bound of the optimal axis interval.
//! \function void AutoSegment::setOptimalMax( DbU::Unit max );
//! Sets the lower bound of the optimal axis interval.
//! \function Interval AutoSegment::_invalidate();
//! Invalidate this segment. The segment is scheduled into the Session
//! revalidation mechanism.
//! \function Interval AutoSegment::revalidate();
//! Mark this segment as valid (unset the Invalidated flag) and update
//! positions. Unlike AutoSegment::invalidate(), it's an atomic method.
//! \function Interval AutoSegment::getMinSpanU() const;
//! \return The AutoSegment \e uniform minimum occupying interval, computed from the
//! constraints of all the supporting aligned AutoContacts.
//! (on X for horizontal and on Y for vertical).
//! \function AutoSegment* AutoSegment::canonize ( unsigned int flags=KbNoFlags );
//! Find and set the canonical AutoSegment from a set of aligneds. For the
//! time beeing we assumes that there is no merging process, so the Segments
//! will only gets more and more fragmented. This implies that a segment can
//! become canonical but it will never revert to normal status.
//!
//! The canonical AutoSegment is the one with the lowest \c Id. This a way
//! of ensuring reproductible results. Note that the canonical one may not
//! be the \e geometrically lowest one.
//!
//! \remark Canonical aware method.
//! \function Interval AutoSegment::computeOptimal( set<AutoSegment*>& processeds );
//! \param processeds A set of already processeds AutoSegment. Used by the
//! caller function to avoid doing again the computation
//! on an AutoSegment from an already proccessed aligned set.
//! Compute the optimal axis interval for the aligned set.
//!
//! \remark Canonical aware method.
//! \function void AutoSegment::invalidate( unsigned int flags=KbPropagate );
//! Invalidate this AutoSegment, or if the Katabatic::KbPropagate flags
//! is set, the whole set of aligned segments.
//!
//! \remark If Katabatic is in the destruction stage, this function does nothing.
//! \remark Canonical aware method.
//! \function void AutoSegment::setAxis( DbU::Unit axis, unsigned int flags=0 );
//! \param axis The new position of the axis.
//! \param flags See KbRealignate.
//!
//! Set the axis of an aligned set. This method does nothing if not called
//! on the canonical AutoSegment of the set. If the new value of the axis
//! is equal to the previous one, nothing is done (non-canonical AutoSegment
//! are not looked after). To force an actual axis set, with invalidation of
//! the whole AutoSegment set, set the KbRealignate flag.
//!
//! \remark Canonical aware method.
//! \function bool AutoSegment::toConstraintAxis();
//! If the AutoSegment axis is outside the constraint interval, put it on
//! nearest bound. This method is active only on canonical AutoSegments.
//!
//! \return \true if an actual axis change is made.
//!
//! \remark Canonical aware method.
//! \function bool AutoSegment::toOptimalAxis();
//! If the AutoSegment axis is outside the optimal interval, put it on
//! nearest bound. This method is active only on canonical AutoSegments.
//!
//! \return \true if an actual axis change is made.
//!
//! \remark Canonical aware method.
//! \function AutoSegments AutoSegment::getAligneds ( unsigned int flags );
//! The Collection of AutoSegments that are aligned on this one
//! through AutoContactHTee or AutoContactVTee. If the \c flags
//! contains Katabatic::KbWithPerpands, the Collection will also
//! includes the AutoSegments directly perpandiculars to the whole
//! aligned set.
//! \function AutoSegments AutoSegment::getPerpandiculars ();
//! The Collection of all AutoSegments directly perpandiculars to the
//! whole aligned set.
//! \function AutoSegments AutoSegment::getOnSourceContact ( unsigned int direction );
//! \sreturn The Collection of AutoSegment in \c direction that are on this segment
//! source contact.
//! \function AutoSegments AutoSegment::getOnTargetContact ( unsigned int direction );
//! \sreturn The Collection of AutoSegment in \c direction that are on this segment
//! target contact.
//! \function AutoSegment::~AutoSegment ()
//! AutoSegment destructor. It is not directly accessible, instead use
//! one flavor of the AutoSegment::create().
//! \function AutoSegment::AutoSegment ( Segment* segment );
//! AutoSegment constructor. It is not directly accessible, instead use
//! one flavor of the AutoSegment::create().
//! \function void AutoSegment::_preCreate( AutoContact* source, AutoContact* target );
//! Perform sanity checks before allowing the actual creation of an
//! AutoSegment. If an error occurs throw an exception.
//!
//! Check for:
//! - \c source and \c target must not be \NULL.
//! - \c source and \c target must be different.
//! \function void AutoSegment::_postCreate ();
//! Perform operations that, given the data structure cannot be done
//! in the constructor. Also allows for sharing code with the derived
//! classes. Currently:
//! - Invalidate the whole net (topology change).
//! - Insert the AutoSegment in the lookup/Session machanism.
//! - Call AutoSegment::invalidate().
//! - Call AutoSegment::updateOrient().
//! - Call AutoSegment::updatePositions().
//! \function void AutoSegment::_preDestroy ();
//! Perform operations that must be done before the actual destructor is
//! called. Merely whidrawn the AutoSegment from the lookup/Session mechanism.
//! \function bool AutoSegment::reduce ();
//! Sets the segment into reduced state.
//!
//! \sreturn \true if the operation did succeed. The layer will not be actually changed
//! until the Katabatic database is saved/destroyed.
//!
//! A segment can be reduced if:
//! - Source & target are AutoContactTurn.
//! - It is either <em>spin top</em> or <em>spin bottom</em>, that is
//! connecting perpandiculars both in the same layer.
//! - Has a length less or equal one pitch in the perpandicular direction.
//! - Neither of the perpandicular are also reduceds.
//!
//! \image html reduce-1.png "Reduce Example"
//!
//! If segment \c id:12 is reduced, it prevents \c id:10 & \c id:14 to
//! be also reduced, by increasing the \c _reduced counter. In this
//! example \c id:14 is <em>spin top</em> and \c id:12 is <em>spin bottom</em>.
//!
//! If we reduce two adjacent segments, one will go up while the other
//! will go down (they will actually exchange their layers), it will
//! thus defeat the purpose of creating a <em>same layer</em> dogleg.
//! Besides, the turn contact between them will be changed into a pure
//! metal one, generating a disconnexion...
//!
//! \see AutoSegment::raise()
//! \function bool AutoSegment::raise ();
//! Get a segment out of \e reduced state.
//!
//! \sreturn \true if a state change did really take place.
//!
//! \see AutoSegment::reduce()
//! \function AutoSegment* AutoSegment::makeDogleg ( AutoContact* from );
//! \param from The AutoContact \e from which we want to make a dogleg.
//!
//! This method is dedicated for the restauration of topology connexity on
//! AutoContcact after a layer change on one of their connected AutoSegment.
//!
//! It perform three operations:
//! -# Create a dogleg on the AutoSegment (using the normal GCell variant).
//! -# Adjust the layers of the dogleg according whether we are going \e up
//! or \e down from the AutoContact \c from to the segment.
//! -# Returns the new AutoSegment connected to \c from (it may be the
//! same as before, \b if the AutoContact is the source of the
//! segment).
//! \function unsigned int AutoSegment::makeDogleg ( GCell* doglegGCell, unsigned int flags=KbNoFlags );
//! Make a dogleg <em>in a set of aligned segments</em>, thus the dogleg
//! may not be created on \c this segment but in the one which is under
//! \c doglegGCell.
//!
//! \sreturn A flag telling if the above or below layer was used for the
//! perpandicular segment (Katabatic::KbUseAboveLayer or
//! Katabatic::KbUseBelowLayer).
//! \function unsigned int AutoSegment::makeDogleg ( Interval interval, unsigned int flags=KbNoFlags );
//! Make a dogleg <em>in a set of aligned segments</em>, thus the dogleg
//! may not be created on \c this segment but in one which span intersect
//! \c interval.
//!
//! \sreturn A set of flags telling if the break has occured on the left candidate
//! (Katabatic::KbDoglegOnLeft) or right (Katabatic::KbDoglegOnRight).
//! it is combined with the flag telling if the above or below layer was
//! used for the dogleg. In case of failure, zero is returned.
//!
//! Break the set of aligned segments so the break point is \e outside
//! \c interval. The break point so can occurs on the \e left of the
//! interval (Katabatic::KbDoglegOnLeft) or on the \e right of the
//! interval (Katabatic::KbDoglegOnRight). When the set of aligned
//! segments fully enclose \c interval, a choice has to be made between
//! the left and right candidate. The rules are as follow:
//! - A \e left candidate include the \e min of the interval into
//! it's span.
//! - A \e right candidate include the \e max of the interval into
//! it's span.
//! - In certain topologies, there can be more than left or right
//! candidates (more than one segment of the set intersect the
//! bounds of the interval). Thoses candidates are ecludeds.
//! - If the two candidates are avalaibles, we choose the one
//! with the greated \e native constraints.
//! - In case of strict equality, the left candidate is choosen.
//!
//! \image html _makeDogleg-4.png "Example Case 4"
//! \function unsigned int AutoSegment::_makeDogleg ( GCell* doglegGCell, unsigned int flags );
//! <b>This method is the workhorse for the various dogleg and topology
//! restauration methods.</b> It is the atomic method that actually
//! make the dogleg on \b this segment.
//!
//! \sreturn Katabatic::KbUseAboveLayer if the dogleg is using the \e above layer
//! (Katabatic::KbUseBelowLayer for the below layer).
//!
//! Break the current segment in two (a.k.a. making a dogleg).
//! - The segment is broken inside \c doglegGCell.
//! - Two new segments are createds, one perpandicular and one parallel.
//! - The original segment is always kept attached to the \e source.
//! (the new parallel fragment is attached to the \e target).
//! - The perpandicular segment is in the layer \e above by default.
//! If we are already on the topmost routing layer, the \e below
//! layer is used.
//! - If the segment pass through the breaking GCell, it's axis is set
//! into the center. If the segment is local, the axis is the middle
//! of the segment.
//! - The Local/Global kind of the original segment is updated.
//! The local/global status is computed by the constructor of the AutoSegment
//! for the perpandicular and the new parallel.
//! - The terminal state is updated. If the segment is a strong terminal
//! the part that is no longer directly connected to the terminal is
//! demoted to Katabatic::SegWeakTerminal1.
//! - The perpandicular is obviously a canonical. If the broken segment
//! is canonical, the original \b is left canonical and only the new parallel
//! is re-canonized. Otherwise, we re-canonise both sets of aligned segments
//! (the one on the source and the one on the target).
//! - The three segments are added to the session dogleg stack.
//!
//! \red{After this method call the net topology is guarantee to be valid.}
//!
//! \image html _makeDogleg-1.png "Example Case 1"
//! \image html _makeDogleg-2.png "Example Case 2"
//! \function bool AutoSegment::moveULeft ();
//! <b>This function do not manage an aligned set. It applies on \c this
//! segment only.</b>
//!
//! Displace an Horizontal or Vertical segment to the GCell below (a.k.a.
//! lower or inferior). Rules for displacement:
//! - The segment must be connected at both end to a turn contact
//! (we do not want to manage more complex cases for the time beeing).
//! - And, of course, the segment must not already by on the bottomost
//! GCell...
//!
//! The displacement take care of:
//! - Managing the status of the various perpandiculars. The stretched
//! one are made global if needed. The shrinked one made local, if
//! needed.
//! - The supporting AutoContact (source & target) are changed of
//! GCell.
//! - If the segment is global, the go-through GCells are updateds.
//!
//! \sreturn \true if the move has succeeded.
//!
//! \image html moveULeft-1.png "moveULeft() for an Horizontal"
//! \function bool AutoSegment::moveURight ();
//! <b>This function do not manage an aligned set. It applies on \c this
//! segment only.</b>
//!
//! Displace an Horizontal or Vertical segment to the GCell above (a.k.a.
//! upper or superior). Rules for displacement:
//!
//! \sa AutoSegment::moveULeft() for a complete description.
//! \function void AutoSegment::slacken ( unsigned int flags );
//!
//! If the the AutoSegment is attached trough source and/or target to a
//! terminal with too tight constraints, create a dogleg on overconstrained
//! extremities.
//!
//! If \c flags contains Katabatic::KbPropagate, not only the current segment will be
//! looked up, but the whole aligned set. Note that due to the structure of
//! the database, there can be no more than two terminal connected segments
//! on the whole set (one on each extremity).
//!
//! If \c flags contains Katabatic::KbHalfSlacken, the number of tracks under which
//! the constraints are considered too tight is 3. Otherwise it is 10, that is a
//! whole GCell side span. This flag should be used when a long set of global
//! wire is overconstrained by only one of it's terminal, the other one offering
//! sufficient slack (typically: 8).
//!
//! The segment will also be slackened from it's terminal if the difference
//! between the current slack (resulting from all the constraints of the
//! aligned set) and the native slack is less than 3 tracks. This case means
//! that we are already near the native slack and it not sufficent enough
//! a degree of freedom.
//!
//! \image html _slacken-1.png "slacken() for an Horizontal"
//!
//! The \c slacken() method reject the slackening of short locals as shown in
//! figure \b 2.a. One way or another, we must connect to the terminal through
//! \b this short local. If we cannot place it, breaking it in two other
//! short local wouldn't help. In fact, it will only clutter more the GCell
//! and make subsequent routing more difficult.
//!
//! The figures \b 2.b and \b 2.c shows the special case of slackening an
//! horizontal from an \e horizontal terminal. In the original configuration,
//! the slack on segment \c id:10 is null, it's only choice is to be aligned
//! with the terminal. If a slackening is requested, it generally implies that
//! the horizontal track is blocked, and close to the terminal. Based on thoses
//! hypothesis, when we slacken the segment \c id:10 we impose that the
//! \e source contact is \b fixed on the terminal itself. That is, the segment
//! \c id:10 will be reduced to a zero-length and we made an immediate turn
//! (see \b 2.c ).
//!
//! \image html _slacken-2.png "slacken() for an Horizontal (special cases)"
//! \function bool AutoSegment::reduceDoglegLayer ();
//!
//! Perform the actual layer change on a reduced segment. This method is to
//! be called juste before destroying the Katabatic database.
//!
//! \sreturn \true if a change occurs.
}