-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Semigroup actions, groups, and torsors.
--   
--   Acts and torsors model types which can be transformed under the action
--   of another type.
--   
--   A prototypical example is affine space, which has an action by
--   translation: given any two points in affine space, there is a unique
--   translation that brings one to the other.
--   
--   This can be useful in a library keeping track of time: on top of
--   needing to keep track of units, one also needs to distinguish between
--   absolute time (time stamps) and relative time (time differences). The
--   operations one expects in this situation are:
--   
--   <ul>
--   <li>Addition and subtraction of time differences: time differences
--   form a (commutative) group.</li>
--   <li>Translation of an absolute time by a time difference: there is an
--   action of relative time on absolute time.</li>
--   <li>Given two absolute times, one can obtain the time difference
--   between them: absolute time is a torsor under relative time.</li>
--   </ul>
--   
--   This library provides a convenient framework which helps to avoid
--   mixing up these two different notions.
--   
--   A fleshed out example is available at
--   <a>Acts.Examples.MusicalIntervals</a>, which showcases the use of
--   actions and torsors in the context of musical intervals and harmony.
--   It also demonstrates common usage patterns of this library, such as
--   how to automatically derive instances.
--   
--   See also the project readme, which includes a simple example with 2D
--   affine space.
@package acts
@version 0.1.0.0


-- | A <a>Group</a> is a <a>Monoid</a> for which the monoid operation can
--   be undone.
--   
--   That is, &lt;math&gt; is a group if each &lt;math&gt; has an inverse
--   element &lt;math&gt; such that
--   
--   &lt;math&gt;
--   
--   Such inverses are necessarily unique.
--   
--   In Haskell, groups are mostly useful to describe objects possessing
--   certain symmetries (such as translation or rotation).
--   
--   To automatically derive <a>Group</a> instances, you can:
--   
--   <ul>
--   <li>Use <tt>DerivingVia</tt> to coerce an existing instance:</li>
--   </ul>
--   
--   <pre>
--   &gt; newtype Seconds   = Seconds { getSeconds :: Double }
--   &gt; newtype TimeDelta = TimeDelta { timeDeltaInSeconds :: Seconds }
--   &gt;   deriving ( Semigroup, Monoid, Group )
--   &gt;     via Sum Double
--   </pre>
--   
--   <ul>
--   <li>Use <a>Generic</a> and <a>Generically</a>:</li>
--   </ul>
--   
--   <pre>
--   &gt; data MyRecord
--   &gt;   = MyRecord
--   &gt;   { field1 :: Sum Double
--   &gt;   , field2 :: Product Double
--   &gt;   , field3 :: Ap [] ( Sum Int, Sum Int )
--   &gt;   }
--   &gt;   deriving Generic
--   &gt;   deriving ( Semigroup, Monoid, Group )
--   &gt;     via Generically MyRecord
--   </pre>
module Data.Group

-- | A <a>Group</a> is a <a>Monoid</a> with inverses:
--   
--   <ul>
--   <li><pre> inverse g &lt;&gt; g = g &lt;&gt; inverse g =
--   mempty</pre></li>
--   <li><pre> inverse (g &lt;&gt; h) = inverse h &lt;&gt; inverse
--   g</pre></li>
--   </ul>
class Monoid g => Group g

-- | Group inversion anti-homomorphism.
inverse :: Group g => g -> g

-- | Take the <tt>n</tt>-th power of an element.
gtimes :: (Group g, Integral n) => n -> g -> g

-- | Data type to keep track of a pair of inverse elements.
data Isom a
(:|:) :: a -> Dual a -> Isom a
[to] :: Isom a -> a
[from] :: Isom a -> Dual a
infix 7 :|:
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Group.Isom a)
instance GHC.Generics.Generic1 Data.Group.Isom
instance GHC.Generics.Generic (Data.Group.Isom a)
instance Data.Data.Data a => Data.Data.Data (Data.Group.Isom a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Group.Isom a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Group.Isom a)
instance Data.Group.Group a => Data.Group.Group (r -> a)
instance Data.Group.Group a => Data.Group.Group (GHC.Types.IO a)
instance Data.Group.Group a => Data.Group.Group (GHC.ST.ST s a)
instance Data.Group.Group a => Data.Group.Group (Data.Ord.Down a)
instance Data.Group.Group a => Data.Group.Group (Data.Functor.Identity.Identity a)
instance Data.Group.Group a => Data.Group.Group (Data.Functor.Const.Const a b)
instance Data.Group.Group a => Data.Group.Group (Data.Functor.Contravariant.Op a b)
instance Data.Group.Group (f p) => Data.Group.Group (GHC.Generics.Rec1 f p)
instance Data.Group.Group (f p) => Data.Group.Group (GHC.Generics.M1 i c f p)
instance Data.Group.Group g => Data.Group.Group (GHC.Generics.K1 i g p)
instance Data.Group.Group g => Data.Group.Group (GHC.Generics.Par1 g)
instance Data.Group.GGroup f => Data.Group.GGroup (GHC.Generics.Rec1 f)
instance Data.Group.GGroup f => Data.Group.GGroup (GHC.Generics.M1 i c f)
instance (GHC.Generics.Generic g, GHC.Base.Monoid (GHC.Generics.Rep g ()), Data.Group.GGroup (GHC.Generics.Rep g)) => Data.Group.Group (Generic.Data.Internal.Generically.Generically g)
instance Data.Group.GGroup GHC.Generics.U1
instance Data.Group.Group g => Data.Group.GGroup (GHC.Generics.K1 i g)
instance (Data.Group.GGroup f1, Data.Group.GGroup f2) => Data.Group.GGroup (f1 GHC.Generics.:*: f2)
instance (TypeError ...) => Data.Group.GGroup GHC.Generics.V1
instance (TypeError ...) => Data.Group.GGroup (f1 GHC.Generics.:+: f2)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Data.Group.Isom a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Group.Isom a)
instance GHC.Base.Monoid a => Data.Group.Group (Data.Group.Isom a)
instance Data.Group.Group ()
instance GHC.Num.Num a => Data.Group.Group (Data.Semigroup.Internal.Sum a)
instance GHC.Real.Fractional a => Data.Group.Group (Data.Semigroup.Internal.Product a)
instance Data.Group.Group a => Data.Group.Group (Data.Semigroup.Internal.Dual a)
instance (Data.Group.Group a, GHC.Base.Applicative f) => Data.Group.Group (Data.Monoid.Ap f a)
instance Data.Group.Group (Data.Proxy.Proxy p)
instance (Data.Group.Group g1, Data.Group.Group g2) => Data.Group.Group (g1, g2)
instance (Data.Group.Group g1, Data.Group.Group g2, Data.Group.Group g3) => Data.Group.Group (g1, g2, g3)
instance (Data.Group.Group g1, Data.Group.Group g2, Data.Group.Group g3, Data.Group.Group g4) => Data.Group.Group (g1, g2, g3, g4)
instance (Data.Group.Group g1, Data.Group.Group g2, Data.Group.Group g3, Data.Group.Group g4, Data.Group.Group g5) => Data.Group.Group (g1, g2, g3, g4, g5)
instance Data.Group.Group (GHC.Generics.U1 p)
instance (Data.Group.Group (f1 p), Data.Group.Group (f2 p)) => Data.Group.Group ((GHC.Generics.:*:) f1 f2 p)


-- | An <a>Act</a> of a semigroup &lt;math&gt; on a type &lt;math&gt; gives
--   a way to transform terms of type &lt;math&gt; by terms of type
--   &lt;math&gt;, in a way that is compatible with the semigroup operation
--   on &lt;math&gt;.
--   
--   In the special case that there is a unique way of going from one term
--   of type &lt;math&gt; to another through a transformation by a term of
--   type &lt;math&gt;, we say that &lt;math&gt; is a torsor under
--   &lt;math&gt;.
--   
--   For example, the plane has an action by translations. Given any two
--   points, there is a unique translation that takes the first point to
--   the second. Note that an unmarked plane (like a blank piece of paper)
--   has no designated origin or reference point, whereas the set of
--   translations is a plane with a given origin (the zero translation).
--   This is the distinction between an affine space (an unmarked plane)
--   and a vector space. Enforcing this distinction in the types can help
--   to avoid confusing absolute points with translation vectors.
--   
--   Simple <a>Act</a> and <a>Torsor</a> instances can be derived through
--   self-actions:
--   
--   <pre>
--   &gt; newtype Seconds   = Seconds { getSeconds :: Double }
--   &gt;   deriving ( Act TimeDelta, Torsor TimeDelta )
--   &gt;     via TimeDelta
--   &gt; newtype TimeDelta = TimeDelta { timeDeltaInSeconds :: Seconds }
--   &gt;   deriving ( Semigroup, Monoid, Group )
--   &gt;     via Sum Double
--   </pre>
module Data.Act

-- | A left <b>act</b> (or left <b>semigroup action</b>) of a semigroup
--   <tt>s</tt> on <tt>x</tt> consists of an operation
--   
--   <pre>
--   (•) :: s -&gt; x -&gt; x
--   </pre>
--   
--   such that:
--   
--   <pre>
--   a • ( b • x ) = ( a &lt;&gt; b ) • x
--   </pre>
--   
--   In case <tt>s</tt> is also a <a>Monoid</a>, we additionally require:
--   
--   <pre>
--   mempty • x = x
--   </pre>
--   
--   The synonym <tt> act = (•) </tt> is also provided.
class Semigroup s => Act s x

-- | Left action of a semigroup.
(•) :: Act s x => s -> x -> x

-- | Left action of a semigroup.
act :: Act s x => s -> x -> x
infixr 5 `act`
infixr 5 •

-- | Transport an act:
--   
transportAction :: (a -> b) -> (b -> a) -> (g -> b -> b) -> g -> a -> a

-- | Trivial act of a semigroup on any type (acting by the identity).
newtype Trivial a
Trivial :: a -> Trivial a
[getTrivial] :: Trivial a -> a

-- | A left <b>torsor</b> consists of a <i>free</i> and <i>transitive</i>
--   left action of a group on an inhabited type.
--   
--   This precisely means that for any two terms <tt>x</tt>, <tt>y</tt>,
--   there exists a <i>unique</i> group element <tt>g</tt> taking
--   <tt>x</tt> to <tt>y</tt>, which is denoted <tt> y &lt;-- x </tt> (or
--   <tt> x --&gt; y </tt>, but the left-pointing arrow is more natural
--   when working with left actions).
--   
--   That is <tt> y &lt;-- x </tt> is the <i>unique</i> element satisfying:
--   
--   <pre>
--   ( y &lt;-- x ) • x = y
--   </pre>
--   
--   Note the order of composition of <tt>&lt;--</tt> and <tt>--&gt;</tt>
--   with respect to <tt>&lt;&gt;</tt>:
--   
--   <pre>
--   ( z &lt;-- y ) &lt;&gt; ( y &lt;-- x ) = z &lt;-- x
--   </pre>
--   
--   <pre>
--   ( y --&gt; z ) &lt;&gt; ( x --&gt; y ) = x --&gt; z
--   </pre>
class (Group g, Act g x) => Torsor g x

-- | Unique group element effecting the given transition
(<--) :: Torsor g x => x -> x -> g

-- | Unique group element effecting the given transition
(-->) :: Torsor g x => x -> x -> g
infix 7 -->
infix 7 <--

-- | Given
--   
--   <ul>
--   <li>&lt;math&gt; acting on &lt;math&gt;,</li>
--   <li>&lt;math&gt; a torsor under &lt;math&gt;,</li>
--   <li>a map &lt;math&gt;,</li>
--   </ul>
--   
--   this function returns the unique element &lt;math&gt; making the
--   following diagram commute:
--   
intertwiner :: forall h g a b. (Act g a, Torsor h b) => g -> (a -> b) -> a -> h
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Act.Trivial a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.Act.Trivial a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Data.Act.Trivial a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Act.Trivial a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Act.Trivial a)
instance GHC.Generics.Generic1 Data.Act.Trivial
instance GHC.Generics.Generic (Data.Act.Trivial a)
instance Data.Data.Data a => Data.Data.Data (Data.Act.Trivial a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Act.Trivial a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Act.Trivial a)
instance Data.Act.Act Data.Semigroup.Internal.Any GHC.Types.Bool
instance Data.Act.Act Data.Semigroup.Internal.All GHC.Types.Bool
instance GHC.Num.Num a => Data.Act.Act (Data.Semigroup.Internal.Sum a) a
instance GHC.Num.Num a => Data.Act.Act (Data.Semigroup.Internal.Product a) a
instance GHC.Classes.Ord a => Data.Act.Act (Data.Semigroup.Max a) a
instance GHC.Classes.Ord a => Data.Act.Act (Data.Semigroup.Min a) a
instance Data.Act.Act s a => Data.Act.Act s (Data.Functor.Const.Const a b)
instance GHC.Num.Num a => Data.Act.Torsor (Data.Semigroup.Internal.Sum a) a
instance Data.Group.Group g => Data.Act.Torsor g g
instance GHC.Base.Semigroup s => Data.Act.Act s (Data.Act.Trivial a)
instance GHC.Base.Semigroup s => Data.Act.Act s s
instance Data.Act.Act () x
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2) => Data.Act.Act (s1, s2) (x1, x2)
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2, Data.Act.Act s3 x3) => Data.Act.Act (s1, s2, s3) (x1, x2, x3)
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2, Data.Act.Act s3 x3, Data.Act.Act s4 x4) => Data.Act.Act (s1, s2, s3, s4) (x1, x2, x3, x4)
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2, Data.Act.Act s3 x3, Data.Act.Act s4 x4, Data.Act.Act s5 x5) => Data.Act.Act (s1, s2, s3, s4, s5) (x1, x2, x3, x4, x5)
instance (Data.Act.Act s x, GHC.Base.Functor f) => Data.Act.Act s (Data.Monoid.Ap f x)
instance (GHC.Base.Semigroup s, Data.Act.Act s a) => Data.Act.Act (Data.Semigroup.Internal.Dual s) (Data.Functor.Contravariant.Op b a)
instance (GHC.Base.Semigroup s, Data.Act.Act s a, Data.Act.Act t b) => Data.Act.Act (Data.Semigroup.Internal.Dual s, t) (a -> b)
instance (Data.Act.Act g x, Data.Group.Group g) => Data.Act.Act (Data.Semigroup.Internal.Dual g) x
instance (Data.Group.Group g, Data.Act.Act g a) => Data.Act.Act g (Data.Semigroup.Internal.Endo a)


-- | Cyclic groups: integers modulo <tt>n</tt> (clock arithmetic).
module Data.Group.Cyclic

-- | Cyclic group of order <tt>n</tt>: integers with addition modulo
--   <tt>n</tt>.
data Cyclic n

-- | Smart pattern and constructor for elements of cyclic groups.
pattern Cyclic :: forall n. KnownNat n => Int -> Cyclic n

-- | Obtain a representative in the range &lt;math&gt;.
getCyclic :: forall n. KnownNat n => Cyclic n -> Int

-- | Synonym for finite cyclic group.
type C (n :: Nat) = Cyclic n

-- | Synonym for infinite cyclic group.
type Z = Sum Int

-- | Newtype for cycling through elements in a finite enumeration.
--   
--   <pre>
--   data ABCD = A | B | C | D 
--     deriving stock ( Enum, Bounded )
--     deriving ( Act ( Cyclic 4 ), Torsor ( Cyclic 4 ) )
--       via CyclicEnum ABCD
--   </pre>
--   
--   <pre>
--   &gt; act ( Cyclic 2 ) C
--   A
--   </pre>
--   
--   <pre>
--   &gt; act ( Cyclic (-1) ) A
--   D
--   </pre>
--   
--   <pre>
--   &gt; ( C --&gt; B :: Cyclic 4 )
--   Cyclic 3
--   </pre>
--   
--   <b>Warning</b> It is unfortunately not checked that the size of the
--   group matches the size of the finite enumeration. Please manually
--   ensure this condition.
newtype CyclicEnum a
CyclicEnum :: a -> CyclicEnum a
[getCyclicEnum] :: CyclicEnum a -> a

-- | Nontrivial element of cyclic group of order 2.
pattern Involution :: Cyclic 2

-- | Act by an involution.
involution :: Act (Cyclic 2) x => x -> x

-- | Natural complex representations of finite cyclic groups as roots of
--   unity.
rootOfUnity :: forall a n. (KnownNat n, Floating a) => Cyclic n -> Complex a
instance Control.DeepSeq.NFData (Data.Group.Cyclic.Cyclic n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Data.Group.Cyclic.Cyclic n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Data.Group.Cyclic.Cyclic n)
instance GHC.Classes.Ord (Data.Group.Cyclic.Cyclic n)
instance GHC.Classes.Eq (Data.Group.Cyclic.Cyclic n)
instance GHC.Generics.Generic1 Data.Group.Cyclic.Cyclic
instance GHC.Generics.Generic (Data.Group.Cyclic.Cyclic n)
instance GHC.Show.Show (Data.Group.Cyclic.Cyclic n)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Group.Cyclic.CyclicEnum a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.Group.Cyclic.CyclicEnum a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Data.Group.Cyclic.CyclicEnum a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Group.Cyclic.CyclicEnum a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Group.Cyclic.CyclicEnum a)
instance GHC.Generics.Generic1 Data.Group.Cyclic.CyclicEnum
instance GHC.Generics.Generic (Data.Group.Cyclic.CyclicEnum a)
instance Data.Data.Data a => Data.Data.Data (Data.Group.Cyclic.CyclicEnum a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Group.Cyclic.CyclicEnum a)
instance GHC.TypeNats.KnownNat n => GHC.Base.Semigroup (Data.Group.Cyclic.Cyclic n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => GHC.Base.Monoid (Data.Group.Cyclic.Cyclic n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Data.Group.Group (Data.Group.Cyclic.Cyclic n)
instance (GHC.Enum.Enum a, GHC.Enum.Bounded a, GHC.TypeNats.KnownNat n) => Data.Act.Act (Data.Group.Cyclic.Cyclic n) (Data.Group.Cyclic.CyclicEnum a)
instance (GHC.Enum.Enum a, GHC.Enum.Bounded a, GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Data.Act.Torsor (Data.Group.Cyclic.Cyclic n) (Data.Group.Cyclic.CyclicEnum a)
instance GHC.TypeNats.KnownNat n => Data.Act.Act (Data.Group.Cyclic.Cyclic n) GHC.Types.Int
instance Data.Act.Act (Data.Group.Cyclic.Cyclic 2) GHC.Types.Bool
instance GHC.Num.Num i => Data.Act.Act (Data.Group.Cyclic.Cyclic 2) (Data.Semigroup.Internal.Sum i)
instance GHC.Real.Fractional i => Data.Act.Act (Data.Group.Cyclic.Cyclic 2) (Data.Semigroup.Internal.Product i)
instance GHC.Num.Num a => Data.Act.Act (Data.Group.Cyclic.Cyclic 2) (Data.Complex.Complex a)