COUPLE_DISTANCE is the distance between (the center reference points of) two dancers standing side by side, face to face, or back to back.

FORMATION_ROLES maps SquareDanceFormations to Roles.

FULL_CIRCLE represents a change in direction of 360 degrees.

ROLE_FORMATIONS maps from a Role to the formations that can identify it.

AllPresent(::SDSquare)

AllPresent is a fact that is asserted to the knowledgebase by SDSquareHasAttendanceRule when all of the Dancers in an SDSquare are present.

It can be used as a trigger for rules that depend on all Dancers having an associated DancerState.

AndRoll(; role=EveryOne())

CallerLab Plus call.

Timing: CallerLab: 2.

Attendance(::SDSquare)

Attendance is a fact in the knowledgebase that keeps track of how many DancerStates in a square are present.

This is necessary because tests like encroached_on can only provide a correct result if all of the DanecerStates are available for consideration.

When all of the Dancers of s set have DancerStates, then Attendance emits an AllPresent fact.

Note that Attendance contains mutable data - but once an Attendance is created, only the values in its present field are changed.

AttendanceRule

AttendanceRule is the rule that updates an Attendance as new DancerStates are asserted to the knowledgebase, and ultimately asserts AllPresent.

BackToBack represents a formation of two dancers with their backs facing each other.

BackToBackCouples is a formation that includes two Couple formations that have their backs to each other.

BackToBackCouplesRule is the rule for identifying the BackToBackCouples formation.

BeforeEightChain is a formation of eight dancers (four couples) lined up, and is the starting formation for the "eight chain thru" call. It can result from doing "centers pass thru" from a FacingTandemCouples formation.

→←→←
→←→←

BeforeEightChainRule is the rule for recognizing BeforeEightChain formations.

BeforeTradeBy is a formation of eight dancers (four couples) lined up, and is the starting formation for the call "trade by". It can result from doing a "centers pass thru" from a BeforeEightChain formation.

←→←→
←→←→

BeforeTradeByRule is the rule for recognizing BeforeTradeBy formations.

Bounds(dss::Vector{DancerState}; margin = COUPLE_DISTANCE / 2)

represents the bounding rectangle surrounding the specified DancerStates. If margin is 0 then Bounds surrounds just the centers of the dancers.

By default, margin is COUPLE_DISTANCE / 2 so that Bounds describes the space actually occupied by the dancers.

Typically, Bounds objects are constructed from SquareDanceFormations. In this case the values within bounds (min_down`, etc.) are in coordinate space units.

BoxCirculate(; role, half_count)

CallerLab Basic 1 square dance call.

BoxOfFour is the abstract supertype for RHBoxOfFour and LHBoxOfFour.

BoxOfFourRule is the rule for identifying right or left handed "box circulate" formations.

CSSKeyfraneomesAnimation

As the method argument to animate, uses the CSS keyframes to animte SVG.

In my, and others's experience, can't get rotation to work.

CallEngineDebugContext(source_location, relpath, token)

A CallEngineDebugContext can be passed to some functions via the dbgctx keyword argument to provide debugging support.

Do not use the constructor directly, instead use @CallEngineDebugContext, which will automatically provide a source location.

CallSchedule(start_time)

CallSchedule maintains the schedule of the ScheduledCalls that are to be performed. The results of expand_parts are added to the schedule while calls are being executed. The call engine (see do_schedule) runs until the schedule is empty.

CanDoCall(preference, call::SquareDanceCall, formation::SquareDanceFormation)

CanDoCall represents that call can be performed from formation, and doing so has the specified preference.

CatchConflictingDancerStates

Throws an error if there are two different DancerStates that concern the same Dancer.

CircleOfEight represents eight dancers in a circle facing inward.

CircleOfEightFormationRule is the rule for recognizing eight dancers in a circle: CircleOfEight.

CirculatePath(::Vector(DancerState})

CirculatePath represents one path in a "circulate" call.

circulate_paths can return multime CirculatePaths.

Each CirculatePath is constructed from a sequence of DancerStates that represent each whole circulate step along the circulate path.

The `CirculateStation's along a CirculatePath are sorted in promenade (counterclockwise) order. The order of the stations is independent of dancer facing direction.

Intermediate "half circulate" stations are automatically intercolated.

CirculateStation(direction, down, left)
CirculateStation(::DancerState)
CirculateStation(::DancerState, direction)
CirculateStation(::CirculateStation, new_direction)

A CirculateStation represents one point along a CirculatePath.

Collision notes that two dancers are occupying the same space.

ColumnOfFour(lead::Tandem, tail::Tandem, centers::Tandem)

Represents a column of four dancers, each facing the back of the dancer in front of them.

ColumnOfFourRule is the rule for identifying ColumnOfFour formations.

CompletedDoublePassThru is a formation of eight dancers (four couples) lined up, and is the ending formation for the call "double pass thru". It can result from doing a "centers pass thru" from a TradeBy formation.

←←→→
←←→→

CompletedDoublePassThruRule is the rule for rtecognizing CompletedDoublePassThru formations.

Couple(beau::DancerState, belle::DancerState)

Couple represents a formation of two dancers both facing the same direction.

CourtesyTurn(; role=Everyone())

CallerLab Basic-1 call.

Timing: CallerLab: 4.

Dancer(couple_number::Int, ::Gender)

Dancer represents a dancer.

DancerState(dancer, time, direction, down, left)
DancerState(previoous::DancerSTate, time, direction, down, left)

represents the location and facing direction of a single dancer at a moment in time.

time is a number defining a temporal ordering. It could represent a number of beats, for example.

DancerState is also the single dancer SquareDanceFormation. As a SquareDanceFormation, one can call a DancerState to iterate over the dancer states of that formation, that its, itself.

The newest DancerState contains the entire history for its Dancer. The next newest is the value of the newest's previous field, and so on until the very first `DancerState for the Dancer.

DancerStatesNotNewestException

An exception which can be signaled by the call engine if the DancerStates being considered for a call are not the newest DancerStates for their Dancers.

Diamond

Diamonds are like stars, except that one of the MiniWaves is further apart.

DiamondRule

DiamondRule is a rule for identifying diamond formations.

Dosado(; role=Everyone(), handedness=RightHanded())

CallerLab Basic1 call.

Timing: Callerlab: 6, unless coming from and returnuing to a squared set, in which case 8.

DotBackend(directory, title)

Provides a subtype of ContainmentGraphBackend that uses GraphViz Dot.

EightDancerFormation is the abstract supertype of all square dance formations involving eight dancers.

FaceLeft(; role=Everyone(), time=2)

CallerLab Basic 1 square dance call causing dancers to turn 1/4 to their left. The timing defaults to 2 since, according to Taminations, two beats is the duration for QuarterIn and QuarterOut.

Timing: CallerLab does not soecify timing. Assume 1. Can be specified as a parameter.

FaceRight(; role=Everyone(), time=2)

CallerLab Basic 1 square dance call causing dancers to turn 1/4 to their right. The timing defaults to 2 since, according to Taminations, two beats is the duration for QuarterIn and QuarterOut.

Timing: CallerLab does not soecify timing. Assume 1. Can be specified as a parameter.

FaceToFace represents a formation of two dancers facing each other.

FacingCouples is a formation that includes two Couple formations that are facing each other.

FacingCouplesRule is the rule for identifying the FacingCouples formation.

FacingTandemCouples is a formation of eight dancers (four couples) lined up, and is the starting formation for the "double pass thru" call. This formation is more commonly known as "Double Pass Thru".

→→←←
→→←←

FacingTandemCouplesRule is the rule for recognizing the FacingTandemCouples formation.

FormationContainedIn(contained, container)

A fact in the knowledgebase that says that contained is a sub-formation of container.

FormationContextRole

is the abstract supertype for square dance roles which are defined by a dancer's context in a particular formation.

FourDancerFormation is the abstract supertype of all square dance formations involving four dancers.

Gal()

The gal gender, represented by a circle in our SVG diagrams.

Gender represents the gender of a dancer, which might be Guy, Gal or Unspecified.

Unspecified exists for when we want to emphasize gender agnosticism in a diagram.

Gender equality: Guy() == Guy(), Gal() == Gal(), otherwise not equal.

Use opposite to get the opposite gender.

Guy()

The guy gender, represented by a square in our SVG diagrams.

Handedness

square dance formations have a handedness, one of RightHanded(), LeftHanded() or NoHandedness().

opposite of a handedness returns the other handedness. NoHandednessis its own opposite.

Hinge(; role=Everyone(), tile=2)

CallerLab Mainstream call.

Timing: CallerLab: 2.

Identify(; role=Everyone(), time=2)

Implements the Identify square dance call, by having dancers jiggle in place.

InvertedLineOfFour represents an inverted line of four formation with a Couple in the center connecting two MiniWaves.

InvertedLineOfFourRule is the rule for identifying InvertedLineOfFour formations.

LHBoxOfFour represents a left handed "box circulate" formation.

LHMiniWave represents a left handed wave of two dancers.

LHWaveOfEight represents a right handed wave of eight dancers.

LHWaveOfFour represents a left handed wave of four dancers.

LineOfFour represents a line of four dancerrs all facing in the same direction.

LineOfFourRule is the rule for iderntifying a LineOfFour formation.

MiniWave is the abstract supertype for all two dancer waves.

NQuarterTag is the abstract supertype for QuarterTag and ThreeQuarterTag formations.

NoCallOptionsForCall

An exception which can be signalled by the call engine when get_call_options can't identify any formations from which a call can be performed.

ObverseRole(::role)

For roles like CoupleNumbers or DesignatedDancers we can't determine the obverse until we know all of the dancers involved. This serves as a "place holder" until we can determine which dancers have the role that is obverse to the specified Role.

OneByFourFormation is the abstract supertype for 1 by 4 "lines". Concrete supertypes are expected to have a centers field.

OriginalPartnerRule is a rule that identifies the original partners of a square dance set.

OriginalPartners(guy::Dancer, gal::Dancer)

OriginalPartners is a fact in the knowledge base that identifies the original partners in a square.

PartnerHinge(; role=Everyone(), tile=2)

CallerLab Advanced-1 call.

Timing: CallerLab: 2.

PassThru(; role=Everyone())

CallerLab Basic 1 call.

Timing: CallerLab: 2.

PassThru is only proper from FaceToFace or from RHMiniWave (because of the "Ocean Wave Rule"). For LHMiniWave, use StepThru.

PullBy(; role=Everyone(), handedness=RightHanded())

CallerLab Basic 1 call.

Timing: CallerLab doesn't specify timing, but since the timing for PassThru is 2, assume the same for PullBy.

PureSVGAnimation

As the method argument to animate, use pure SVG animate animation. Various sources suggest that SVG animate is deprecated, but it works.

QTWCT is an intermediate result to sypport the rules for recognizing QuarterTag and ThreeQuarterTag.

QTWCTRule is a rule that provides a precursor fact for QuarterTagRule and ThreeQuarterTagRule.

QuarterIn(; role=Everyone())

CalllerLab Advanced 1 call.

Timing: CallerLab: 2.

QuarterOut(; role=Everyone())

CalllerLab Advanced 1 call.

Timing: CallerLab: 2.

QuarterTag represents a quarter tag formation.

QuarterTagRule is the rule for identifying QuarterTag formations.

RHBoxOfFour represents a right handed "box circulate" formation.

RHMiniWave represents a right handed wave of two dancers.

RHWaveOfEight represents a right handed wave of eight dancers.

RHWaveOfFour represents a right handed wave of four dancers.

Respirator(::Vector{DancerState))

Respirator is a device for assisting breating. It performs the bookkeeping associed with tracking the current location of each dancer as adjusted by the breathing algorithm without creating new DancerStates.

Role

is the abstract supertype for all square dance role types.

SDRKnowledgeBase(label)

The type for the root node of our knowledgebase.

SDSquare(dancers)

SDSquare represents the dancers in a square.

make_square(number_of_couples) will return an SDSquare.

SDSquare is a fact that can be asserted to the knowledge base to inform it that the dancers form a square.

other_dancers(::SDSquare, dancers) returns the set of Dancers that are in the SDSquare but are not in dancers.

SquareDanceFormationRule

A rule that ensures that there is an Attendance fact for every SDSquare fact.

ScheduledCall(when, ::SquareDanceCall)

ScheduledCall associates a SquareDanceCall with the time it should be performed.

SlideThru(; role=Everyone())

CallerLab Mainstream call.

Timing: CallerLab: 4.

SquareDanceCall

For each call, a struct is defined that is a subtype of SquareDanceCall.

For each call and each formation it can be done from, a can_do_from method should be defined. If the "Ocean Wave Rule" applies, then a can_do_from method should be defined for that case.

For each call and each formation it can be performed from, either a perform or an expand_parts method should be defined.

SquareDanceFormation is the abstract supertype of all square dance formations.

Each concrete subtype can be callled to get an iterator over all of the DancerStates of the formation.

SquareDanceFormationRule

the group for all rules relating to square dance formations.

SquareDanceRule is the abstract supertype for all rules defined in this package.

SquareHasDancers is a convenience rule for asserting the Dancers from a SDSquare.

SquareThru(; role, handedness, count)

CallerLab Basic 1 square dance call.

Timing: count=1: 2, count=2: 5, count=3: 7 or 8, count=4: 10.

SquaredSet(couples1::FacingCouples, couples2::FacingCouples)

SquaredSet represents a squared set of eight dancers.

SquaredSetFormationRule is the rule for identifying a SquaredSet.

Star

Star represents four dancers holding either right or left hands together in their center. All are facing either clockwise or counterclockwise.

StarRule is the rule for recognizing right or left handed stars.

StarThru(; role=Everyone())

CallerLab Basic-1 call.

Timing: CallerLab: 4.

StepThru(; role=Everyone())

CallerLab Basic 1 square dance call that goes from MiniWave to BackToBack.

Timing: CallerLab doesn't spoecify a timing, but since the specified timing for PassThru is 2 and StepThru must be simpler, assume 1.

StepToAWave(; role=Everyone(), handedness=RightHanded())

CallerLab Basic 2 square dance call that goes from FaceToFace to a MiniWave of the specified handedness. The first half of PassThru.

Timing: 2.

Tandem(leaderLLDancerState, trailer::DancerState)

Tandem repreents a formation of two dancers where the trailer is facing the back of the leader.

TandemCouples is a formation for two Couples in Tandem.

TandemCouplesRule is the rule for identifying the TandemCouples formation.

TemporalFact

Abstract supertype for any facts that have a temporal dependence.

ThreeQuarterTag represents a three quarter tag formation.

ThreeQuarterTagRule is the rule for identifying ThreeQuarterTag formations.

TimeBounds()

Returns an empty TimeBounds interval.

Trade(; role=Everyone(), time=2)

CallerLab Basic call.

Timing: CallerLab: MiniWave: 3, Couple: 4

TwoDancerFormation is the abstract supertype of all square dance formations involving two dancers.

TwoDancerFormationsRule

TwoDancerFormationsRule is the rule for identifying all two dancer formations: Couple, FaceToFace, BackToBack, Tandem, RHMiniWave, and LHMiniWave.

TwoDifferentCouples

TwoDifferentCouples is a preliminary fact that supports the rules for finding FacingCouples, BackToBackCouples and TandemCouples.

TwoDifferentCouplesRule

TwoDifferentCouplesRule is a precursor rule for rules that recognize formations containing at least two couples.

TwoFacedLine represents a two faced line formation.

TwoFacedLineRule is the rule for identifying TwoFacedLine formations.

UTurnBack(; role=Everyone())

CallerLab Basic1 call.

Timing: CallerLab: 2.

UniversalRole

is the abstract type for those roles which might apply regardless of what formation the daners are in.

Unspecified

Unspecified gender is provided just for gender neutral diagraming, where it appears as a square with rounded corners. It is not supported widely through this codebase. For example original partner and original corner are do not support it.

Note that

Unspecified() != Unspecified()

and

opposite(Unspecified())

returns Unspecified().

UnsynchronizedDancersException

An exception which can be signaled by the call engine if the relevant DancerStates are not symchronized to one another.

WaveOfEight is the abstract supertype for right and left handed waves of eight dancers.

WaveOfEightRule is the rule for identifying waves of eight dancers: RHWaveOfEight and LHWaveOfEight.

WaveOfFour is the abstract supertype for right and left handed waves of four dancers.

WaveOfFourRule is the rule for identifying waves of four dancers: RHWaveOfFour and LHWaveOfFour.

_BackToAWave(; role=Everyone(), handedness=RightHanded())

Primitive square dance call that goes from BackToBack to a MiniWave of the specified handedness. The third quarter of Dosado.

Timing: 1.

_EndAt(f::TwoDancerFormation, time=0, swap=true)

Primitive square dance call that causes the dancer to end at the starting location of the other dancer.

If swap is false then the dancer ends in its own starting location instead of that of the other dancer.

_FaceOriginalCorner(; role=Everyone(), time=0)

Primitive square dance call which causes a dancer to face its original corner.

Timing: as specified in the parameter.

_FaceOriginalPartner(; role=Everyone(), time=0)

Primitive square dance call which causes a dancer to face its original partner.

Timing: as specified in the parameter.

_FinishTrade(; role=Everyone, time=2)

a primitive call that represents the second half of Trade from a [Couple](@ref).

_FollowCirculatePaths

_FollowCirculatePaths is an internal helper calll to assist with implementing various circulate calls form various formations.

_GenderedRoll(; role=Everyone(), time=2)

The second part of calls like StarThru and SlideThru. Guy turn one quarter to the right, Gal turn one quarter to the left.

Timing: as specified in the parameter. Defaults to 2. CallerLab says the timing for StarThru is 4, so thisseems reasonable.

_MaybeDiamondPoints is like MiniWave, but with the dancers further apart. _MaybeDiamondPoints allows encroaching dancers. It is used to help recognize Diamonds.

_Meet(; role=Everyone(), duration=0)

Facing dancers move forward until they are close together.

Consider a call like PassThru where the dancers might be close together or some distance apart (like in a squared set). PassThru uses _EndAt to put the dancers in each others previous locations. What if we want the Heads of a squared set to end up in the middle. We have the dancers _Meet first.

_Rest(; role=Everyone(), time)

Primitive square dance call causing dancers to rest in place for the specified time.

Timing: as specified in the parameter.

_UnStepToAWave(; role=Everyone())

Primitive square dance call that goes from a MiniWave to FaceToFace. The first half of PassThru.

Timing: 2. Persimably should have the same timing as StepToAWave

Base.isless(::Dancer, ::Dancer)::Bool

Provides a total ordering for dancers.

advance_schedule_by(sched::CallSchedule, delta)

Move every entry in the schedule forward by delta.

animate(method::AnimationMethod, output_file, dancer_states; bpm=40)

Returns an SVG document fragment that animates the motion of the Dancers in dancer_states.

If output_file ends in ".svg" then the document fragment is written to that file. output_file is still needed so that the relative path to the dancer symbols file canbe determined.

dancer_states should have the most recent DancerState for each Dancer. the previous property of each DancerState is used to determine the Dancer's motion.

bpm or "beats per minute" provides a time scale for the animation. Assuming each unit of time in a DancerState is a single beat, bpm is used to calculate the total duration of one cycle through the animation.

apply_motion(rsp::Respirator, movement::Dict{Dancer, Vector})

Update rsp to reflect the Dancer movement specified in movement.

as_text(call)

Return a textual description of the call as a String.

back_to_a_wave(f::BackToBack, time_delta, h::Union{RightHanded, LeftHanded})::FaceToFace

The back to back dancers back up to firm a miniwave of the specified handedness.

Breating should be done separately.

backward(ds::DancerState, distance, time_delta)::DancerState

Move the Dancer identified by ds backward (based on ds.direction) the specified distance by returning a new dancer state.

behind(focus::DancerState, other::DancerState)::Bool

returns true if other is behind focus.

breathe(playmates::Vector{<:TwoDancerFormation}, everyone::Vector{DancerState})::Vector{DancerState}

Moves the dancers apart such that those that have collided no longer overlap.

playmates is used to inform what direction colliders should be moved in such that playmates are not separated.

everyone includes all DancerStates that are to be affected.

bump_out(bounds::Bounds, amount)

Returns a new Bounds object that is expanded at each edge by amount.

bump_out(bounds::Bounds)

Returns a new Bounds object that is expanded by COUPLE_DISTANCE / 2 on each edge so that instead of encompassing the centers of each Dancer it encompasses whole dancers.

call_schedule_isless(call1::ScqareDanceCall, call2::SquareDanceCall)

We need some way to control the scheduleing order of zero duration calls like _EndAt.

This is kind of a kludge but I've not thought of anything better.

candofrom(::SquareDanceCall, ::SquareDanceFormation)::Int

Determins if the specified call can be performed from the specified formation. A return value of 0 means the call is not appropriate (or not currently supported). Otherwise the return value is a preference level with a higher value indicating more preferable. For example UTurnBack from Couple is more preferable to UTurnBack from DancerState, even though both would be applicable.

can_roll(ds::DancerState)

Determine whether the modifier "and roll" can be applied to the DancerState. If the dancer can roll then can_roll returns a signed rotation value.

This is not useful for "and roll as if you could".

canonicalize(direction)

canonicalizes the direction to be between 0 and 1.

canonicalize_signed(direction)

canonicalizes the direction to be between -1//2 and 1//2.

center(dss)

returns the center of the specified DancerStates as a two element Vector of down and left coordinates.

circulate_paths(::SquareDanceFormation) = CirculatePath[]

For the specified square dance formation, return the CirculatePaths for that formation.

circulate_paths should be specialized for each formation from which a "circulate" call can be called.

collateral_file_relpath(resource_name, html_file_destination)

Returns the path to the named resource in the environment of html_file_destination.

resource_name is one of the keys of HTML_COLLATERAL_FILES.

html_file_destination is the absolute path of the XML or HTML file that is referring to the resource.

collisions(::Respirator)

Returns an iterator over the current collisions in the Respirator.

containment_graph(kb::SDRKnowledgeBase, title, backend::ContainmentGraphBackend)

Visualizes the containment graph for the formations in kb.

title is a title for the graph. It might be used as the base of a file name.

backend says how to visualize the graph.

copy_html_collateral_files()

Copies each of the files identified in HTMLCOLLATERALFILES to each of the directories listed in TARGET_LOCATIONS.

SquareDanceReasoning writes XML and HTML files to various locations. Some of those locations are only accessible in certain circumstances. For example, The package source code hierarchy is not available to documentation foles delivered to the gh-pages branch. copy_html_collateral_files copies the files to where they might be needed. collateral_file_relpath is used to file the most appropriate

Use collateral_file_relpath to get the best reference location for a resource file.

corner_couple_number(::Dancer)

Returns the couple number of the dancer's corner. Since this function has no way of knowing the number of daners in the "square", the value returned nmight require numeric rapping.

current_location(r::Respirator, d::Dancer)

returns the current location of the Dancer as recorded in the Respirator.

dancer_state_roles(formation::SquareDanceFormatio)::AbstractDict{DancerState, Set{Role}}

Returns a dictionary mapping DancerState to a list of Roles that the DancerState holds in the specified formation.

dancer_states(formation)::Vector{DancerState}

Returns a list of the DancerStates in the formation, in no particular order.

direction(formation)

If all of the dancers of formation are facing in the same direction then return that direction. Otherwise get a no such method error.

direction(focus, other)

returns the absolute direction that other is from the point of view of focus. Either argument can be a DancerState or a localtion represented as a two element Vector.

distance(p1, p2)

returns the distance between the two points represented by vectors.

do_call(kb::SDRKnowledgeBase, call::SquareDanceCall; dbgctx = nothing)::SDRKnowledgeBase

Perform the specified square dance call and return an updated knowledgebase. do_call is the entry point into the call engine.

dotescape(::AbstractString)::AbstractString

Escape an ID in the GraphViz Dot language. 'ID' is the fundamental token in Dot.

earliest(ds::DancerState)

Returns the earliest DancerState in the specified DancerState's previous chain.

elt(f, tagname::AbstractString, things...)
elt(tagname::AbstractString, things...)

Return an XML element. f is called with a single argument: either an XML.AbstractXMLNode or a Pair describing an XML attribute to be added to the resulting element.

encroached_on(formations, kb)

Returns the first encroaching DancerState if any of the other contemporary DancerStates in the knowledge base are within the Bounds of the specified formations. Otherwise returns nothing.

expand(bounds::Bounds, ::DancerState)::Bounds

bounds is modified to encompass the additional DancerState.

expand(tb::TimeBounds, ds::DancerState)::TimeBounds

expands tb to encompass the time of the specified DancerStates.

expand_parts(::SquareDanceCall, ::SquareDanceFormation, ::ScheduledCall)

Returns either the ScheduledCall itself, if it has no expansion, or a vector of a ScheduledCall for each part.

The ScheduledCall's when field is the starting time for the call. The pats in the expansion can have their times offset from that.

facing_center(::Dancer, theta)

Used in conjunstion with polar_arrangement to cause the dancer to be facing inward towards the center of the circle.

find_collisions(dss::Vector{DancerState})::Vector{Collision}

Find the DancerStates that have collided with each other.

fixed(x)

truncates ludicrously small floating point numbers.

formation_svg(f::SquareDanceFormation, symbol_uri_base; inline_stylesheet, id=nothing)

Returns an SVG element that illustrates the formation.

symbol_uri_base is a relative URL to the SVG symbols file. See collateral_file_relpath. If symbol_uri_base is the empty string then the dancer symbol definitions will be inlined.

If id is specified, it will be the XML Id of the drawing.

If margin is specified, its the additional space that surrounds the formation.

forward(ds::DancerState, distance, time_delta)::DancerState

Move the Dancer identified by ds forward (based on ds.direction) the specified distance by returning a new dancer state.

fraction(tb::TimeBounds, t)

return where t falls within tb as a fraction. For t == tb.min the result would be 0. For t == tb.max the result would be 100.

 grid_arrangement(dancers::Vector{Dancer}, dancer_indices::Array{<:Integer, 2}, dancer_directions::Array{Rational, 2})

Returns a two dimensional array of DancerStates such that the dancers are arranged in a rectangular grid of the specified dimensions.

dancers is a vector of Dancers indexed by dancer_indices. A dancer index can be 0 to indicate that there is no dancer in that positriion.

dancer_indices and dancer_directions are Arrays of the same dimensions. This determiines the dimensions of the resulting grid.

Alternatively, dancer_directions can be a Vector of strings of the Unicode arrow characters ←, ↑, →, or ↓, with the space character serving as a placeholder where there is no dancer.

The two indices of each array correspond to the down and left coordinates respectively.

handedness(formation)

returns the handedness of a square dance formation: one of RightHanded(), LeftHanded() or NoHandedness()

history(f, ds::DancerState)

Calls f on ds and all of its previous DancerStates in chronological order.

in_bounds(bounds::Bounds, ds::DancerState)::Bool

Returns true if the specified DancerState it located within bounds.

in_bounds(Bounds([ds]), ds) == true

in_front_of(focus::DancerState, other::DancerState)::Bool

returns true if other is in front of focus.

is_original_head(::Dancer)::Bool

returns true if the dancer was originally in a head position.

is_original_side(::Dancer)::Bool

returns true if the dancer was originally in a side position.

jitter(ds::DancerState, time_delta)::DancerState

Adds noise to the position and facing direction of the DancerState. This allows us to test whether our formation recognition rules are sensitive to such noise.

latest_dancer_states(kb)::Dict{Dancer, DancerState}

Return a Dict that provides the latest DancerState for each Dancer.

fleft_hand_in(::Dancer, theta)

Used in conjunstion with polar_arrangement to cause the dancer to be facing in promenade direction with their left shouolder towards the center.

left_of(focus::DancerState, other::DancerState)::Bool

returns true if other is to the left of focus.

leftward(ds::DancerState, distance, time_delta)::DancerState

Move the Dancer identified by ds to the left (based on ds.direction) by the specified distance by returning a new dancer state.

location(thing)

Returns the down and left coordinates of thing as a two wlwment vectore. Thing might already be such a two element vector, for example, as returned by center.

make_kb(kb::SDRKnowledgeBase)

Makes a copy of the knowledge base, but without any TemporalFacts.

make_kb()

Creates SquareDanceReasoning knowledge base with no facts, but with all rules installed.

make_showcase_index_file()

Writes an index file for the choreography Showcase docs directory.

make_square(number_of_couples::Int)::SDSquare

Returns an SDSquare with the specified number of couples.

merge_sorted_iterators(iters)

Merges the contents of the sorted iterables into a single iterator producing those unique elements in order.

motion_for_collision(rsp::Respirator, collision, movement::Dict{Dancer, Vector})

Compute the motions required to resolve the specified collision and add it to movement. Does not apply those motions yet. movement is a Dict mapping Dancer to motion vector.

move(r::Respirator, d::Dancer, down, left)

Applies the relative down and left motion to the Dancer.

near(::DancerState, ::DancerState)

returns true if the two DancerStates are for different dancers and are close enough together (within DANCERNEARDISTANCE).

next_station(path::CirculatePath, ds::DancerState)

Returns the next CirculateStation or nothing for the Dancer specified by DancerState along path.

note_call_text(call::SquareDanceCall)

Record the call and its as_text to a database. Returns the call.

obverse(::Role)::Role

Each role has an obverse role. (I didn't want to overload opposite). At a given time a dancer either has role or role's obverse.

opposite(direction)

returns the direction opposite to the given one.

opposite(::Gender)::Gender

Returns the opposite Gender. Unspecified() is its own opposite.

other_dancers(square::SDSquare, dancers)

Returns the dancers from square that are not listed in the dancers argument.

pass_by(mw::MiniWave, time_delta)::BackToBack

Dancers in a MiniWave pass by each other to end BackToBack.

percentage(tb::TimeBounds, t)

return where t falls within tb as a percentage. For t == tb.min the result would be 0. For t == tb.max the result would be 100.

perform(::SquareDanceCall, ::SquareDanceFormation, ::SDRKnowledgeBase)::SquareDanceFormation

Performs the call on the specified formation and returns the new formation.

playmate(ds::Dancer, f::TwoDancerFormation)::Union{Nothing, Dancer}

If the Dancer is part of the formation then return the other Dancer in the formation, otherwise return nothing.

polar_arrangement(count, center, radius, phase_angle)

Computtes count points in a circle around center (a two element vector of down and left) with the specified radius. Returns a Vector of count Vectors of direction from center point, down and left.

Like all angles in this package, phase_angle ranges from 0 to 1 counterclockwise, with 1 being a full circle. If phase_angle is 0, The first point is placed radius distance up from center.

radius can either be a number or a function of an index in the range of 1::count. This function should return the radius. This is useful when the resulting points need to have different radii.

polar_arrangement(dancers, center, radius, phase_angle, facing_direction)

Arranges dancers in a circle around center (a two element vector of down and left) with the specified radius. Returns a Vector of DaqncerStates.

Like all angles in this package, phase_angle ranges from 0 to 1 counterclockwise, with 1 being a full circle. If phase_angle is 0, The first dancer is placed radius distance down from center. That dancer would be facing the center if their facing direction is 1/2.

facing_direction takes a Dancer and the placement angle of that dancer (angle of the vector from center to dancer) and returns the facing direction for that dancer. See facing_center, right_hand_in, and left_hand_in for examples.

quarter_left(direction)

returns the direction that's a quarter turn left from the given direction.

quarter_right(direction)

returns the direction that's a quarter turn right from the given direction.

restricted_to(call)::Role

Returns the role that call has been restricted to.

Each subtype of SquareDanceCall must have either a role field or a restricted_to method.

resultingDancerStates(rsp::Respirator)

Returns new DancerStates which have had the computed breathing applied to them.

revolve(location, center, sweep, distance_from_center)

Returns a new location as two values(down and left coordinates) that is the result of revolving an object that was at location around center by sweep and changing its distance from the center to distance_from_center.

revolve(ds::DancerState, center, new_direction, time_delta)::DancerState

Revolves the Dancer identified by ds around center (a two element Vector of down and left coordinates) until the Dancer's new facing direction is new_direction. A new DancerState is returned. time_delta is the duration of the revolution operation.

right_hand_in(::Dancer, theta)

Used in conjunstion with polar_arrangement to cause the dancer to be facing in promenade direction with their left shouolder towards the center.

right_of(focus::DancerState, other::DancerState)::Bool

returns true if other is to the right of focus.

rightward(ds::DancerState, distance, time_delta)::DancerState

Move the Dancer identified by ds to the right (based on ds.direction) by the specified distance by returning a new dancer state.

rotate(ds::DancerState, rotation, time_delta)::DancerState

Rotates the dancer idntified by the DancerState in place by rotation.

schedule(sched::CallSchedule, call::SquareDanceCall, at)

Enters call into sched so that it will be performed at the specified time at.

show_formation_containment(kb::SDRKnowledgeBase)

For debugging, show the memory of the FormationContainedInMemoryNode.

showcase(filename::String, title::String, initial_kb, choreography::Vector{SquareDanceCall}; inhibit_call_engine_logging = true; dbgctx = nothing)

Writes a markdown file named filename in the choreography Showcase documentation directory.

title is the title string for the document.

initial_kb is the knowledgebase containing the formations that choreography starts from.

choreography is a vector of the calls to be performed.

If inhibit_call_engine_logging is true then teh usual call engine logging will be suppressed.

If provided, dbgctx should be a CallEngineDebugContext.

square_up(dancers; initial_time = 0)

returns a list of DancerStates for the initial squared set.

step_to_a_wave(f::FaceToFace, time_delta, h::Handedness)::MiniWave

The face to face dancers move up to make a right or left handed miniwave.

Breating should be done separately.

supported_roles(formation)

Returns a list of the Roles that are supported by formation.

those_with_role(::SquareDanceFormation, ::Role)

For the specified formation, returns DancerStates whose dancers fill the specified role.

timeof(::SquareDanceFormation)

Returns the valuie of the time field, which should be the same for all DancerSTate in the formation.

un_step_to_a_wave(f::MiniWave, time_delta)::FaceToFace

The face to face dancers move up to make a right or left handed miniwave.

Breating should be done separately.

uncollide(collisions::Vector{Collision}, dss::Vector{DancerState})
uncollide(collisions::Vector{Collision}, ds::DancerState)
uncollide(collision::Collision, ds::DancerState)

Returns a vector describing how the DancerState's position should be adjusted so that no DancerStates are colliding.

Only the first method (which takes vectors of Collisions and DancerStates) should be called by outside code. The other two are part of the implementation.

uncollide should only move dancers further apart, never closer together.

unit_vector(direction)

Returns a unit vector pointing in direction, which is specified as a fraction of a full circle.

update_from(formation::SquareDanceFormation, newest::Vector{DancerState})

Return a new formation of the same type as formation but with its component DancerStates taken from newest, matching by Dancer.

@CallEngineDebugContext(relpath, token)

Creates a CallEngineDebugContext with an appropriate source locator.