{-# LANGUAGE PatternSynonyms #-}
{-# language Trustworthy #-}
-- |
-- Module       : Data.Group.Free
-- Copyright    : (c) 2020-2021 Reed Mullanix, Emily Pillmore
-- License      : BSD-style
--
-- Maintainer   : Reed Mullanix <reedmullanix@gmail.com>,
--                Emily Pillmore <emilypi@cohomolo.gy>
--
-- Stability    : stable
-- Portability  : non-portable
--
-- This module provides definitions for 'FreeGroup's and 'Data.Group.Free.FreeAbelianGroup's,
-- along with useful combinators.
--
module Data.Group.Free
( -- * Free groups
  FreeGroup(..)
  -- ** Free group combinators
, simplify
, interpret
, interpret'
, present
  -- * Free abelian groups
, FreeAbelianGroup
, pattern FreeAbelianGroup
, mkFreeAbelianGroup
, runFreeAbelianGroup
  -- ** Free abelian group combinators
, abfoldMap
, abmap
, abjoin
, singleton
, abInterpret
) where


import Control.Applicative
import Control.Monad

import Data.Bifunctor
import Data.List (foldl')
import Data.Map (Map)
import qualified Data.Map.Strict as Map
import Data.Group
import Data.Group.Free.Internal
import Data.Group.Order


-- $setup
--
-- >>> import qualified Prelude
-- >>> import Data.Group
-- >>> import Data.Monoid
-- >>> import Data.Semigroup
-- >>> import Data.Word
-- >>> :set -XTypeApplications
-- >>> :set -XFlexibleContexts

-- -------------------------------------------------------------------- --
-- Free groups

-- | A representation of a free group over an alphabet @a@.
--
-- The intuition here is that @Left a@ represents a "negative" @a@,
-- whereas @Right a@ represents "positive" @a@.
--
-- __Note:__ This does not perform simplification upon multiplication or construction.
-- To do this, one should use 'simplify'.
--
newtype FreeGroup a = FreeGroup { FreeGroup a -> [Either a a]
runFreeGroup :: [Either a a] }
    deriving (Int -> FreeGroup a -> ShowS
[FreeGroup a] -> ShowS
FreeGroup a -> String
(Int -> FreeGroup a -> ShowS)
-> (FreeGroup a -> String)
-> ([FreeGroup a] -> ShowS)
-> Show (FreeGroup a)
forall a. Show a => Int -> FreeGroup a -> ShowS
forall a. Show a => [FreeGroup a] -> ShowS
forall a. Show a => FreeGroup a -> String
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [FreeGroup a] -> ShowS
$cshowList :: forall a. Show a => [FreeGroup a] -> ShowS
show :: FreeGroup a -> String
$cshow :: forall a. Show a => FreeGroup a -> String
showsPrec :: Int -> FreeGroup a -> ShowS
$cshowsPrec :: forall a. Show a => Int -> FreeGroup a -> ShowS
Show, FreeGroup a -> FreeGroup a -> Bool
(FreeGroup a -> FreeGroup a -> Bool)
-> (FreeGroup a -> FreeGroup a -> Bool) -> Eq (FreeGroup a)
forall a. Eq a => FreeGroup a -> FreeGroup a -> Bool
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: FreeGroup a -> FreeGroup a -> Bool
$c/= :: forall a. Eq a => FreeGroup a -> FreeGroup a -> Bool
== :: FreeGroup a -> FreeGroup a -> Bool
$c== :: forall a. Eq a => FreeGroup a -> FreeGroup a -> Bool
Eq, Eq (FreeGroup a)
Eq (FreeGroup a)
-> (FreeGroup a -> FreeGroup a -> Ordering)
-> (FreeGroup a -> FreeGroup a -> Bool)
-> (FreeGroup a -> FreeGroup a -> Bool)
-> (FreeGroup a -> FreeGroup a -> Bool)
-> (FreeGroup a -> FreeGroup a -> Bool)
-> (FreeGroup a -> FreeGroup a -> FreeGroup a)
-> (FreeGroup a -> FreeGroup a -> FreeGroup a)
-> Ord (FreeGroup a)
FreeGroup a -> FreeGroup a -> Bool
FreeGroup a -> FreeGroup a -> Ordering
FreeGroup a -> FreeGroup a -> FreeGroup a
forall a.
Eq a
-> (a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
forall a. Ord a => Eq (FreeGroup a)
forall a. Ord a => FreeGroup a -> FreeGroup a -> Bool
forall a. Ord a => FreeGroup a -> FreeGroup a -> Ordering
forall a. Ord a => FreeGroup a -> FreeGroup a -> FreeGroup a
min :: FreeGroup a -> FreeGroup a -> FreeGroup a
$cmin :: forall a. Ord a => FreeGroup a -> FreeGroup a -> FreeGroup a
max :: FreeGroup a -> FreeGroup a -> FreeGroup a
$cmax :: forall a. Ord a => FreeGroup a -> FreeGroup a -> FreeGroup a
>= :: FreeGroup a -> FreeGroup a -> Bool
$c>= :: forall a. Ord a => FreeGroup a -> FreeGroup a -> Bool
> :: FreeGroup a -> FreeGroup a -> Bool
$c> :: forall a. Ord a => FreeGroup a -> FreeGroup a -> Bool
<= :: FreeGroup a -> FreeGroup a -> Bool
$c<= :: forall a. Ord a => FreeGroup a -> FreeGroup a -> Bool
< :: FreeGroup a -> FreeGroup a -> Bool
$c< :: forall a. Ord a => FreeGroup a -> FreeGroup a -> Bool
compare :: FreeGroup a -> FreeGroup a -> Ordering
$ccompare :: forall a. Ord a => FreeGroup a -> FreeGroup a -> Ordering
$cp1Ord :: forall a. Ord a => Eq (FreeGroup a)
Ord)

instance Semigroup (FreeGroup a) where
    (FreeGroup [Either a a]
g) <> :: FreeGroup a -> FreeGroup a -> FreeGroup a
<> (FreeGroup [Either a a]
g') = [Either a a] -> FreeGroup a
forall a. [Either a a] -> FreeGroup a
FreeGroup ([Either a a]
g [Either a a] -> [Either a a] -> [Either a a]
forall a. [a] -> [a] -> [a]
++ [Either a a]
g')

instance Monoid (FreeGroup a) where
    mempty :: FreeGroup a
mempty = [Either a a] -> FreeGroup a
forall a. [Either a a] -> FreeGroup a
FreeGroup []

instance Group (FreeGroup a) where
    invert :: FreeGroup a -> FreeGroup a
invert = [Either a a] -> FreeGroup a
forall a. [Either a a] -> FreeGroup a
FreeGroup
      ([Either a a] -> FreeGroup a)
-> (FreeGroup a -> [Either a a]) -> FreeGroup a -> FreeGroup a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Either a a -> Either a a) -> [Either a a] -> [Either a a]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((a -> Either a a) -> (a -> Either a a) -> Either a a -> Either a a
forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either a -> Either a a
forall a b. b -> Either a b
Right a -> Either a a
forall a b. a -> Either a b
Left)
      ([Either a a] -> [Either a a])
-> (FreeGroup a -> [Either a a]) -> FreeGroup a -> [Either a a]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [Either a a] -> [Either a a]
forall a. [a] -> [a]
reverse
      ([Either a a] -> [Either a a])
-> (FreeGroup a -> [Either a a]) -> FreeGroup a -> [Either a a]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. FreeGroup a -> [Either a a]
forall a. FreeGroup a -> [Either a a]
runFreeGroup

instance Eq a => GroupOrder (FreeGroup a) where
    -- TODO: It performs simplify each time @order@ is called.
    --   Once "auto-simplify" is implemented, this
    --   call of simplify should be removed.
    order :: FreeGroup a -> Order
order FreeGroup a
g | FreeGroup a -> FreeGroup a
forall a. Eq a => FreeGroup a -> FreeGroup a
simplify FreeGroup a
g FreeGroup a -> FreeGroup a -> Bool
forall a. Eq a => a -> a -> Bool
== FreeGroup a
forall a. Monoid a => a
mempty = Natural -> Order
Finite Natural
1
            | Bool
otherwise = Order
Infinite

instance Functor FreeGroup where
    fmap :: (a -> b) -> FreeGroup a -> FreeGroup b
fmap a -> b
f (FreeGroup [Either a a]
g) = [Either b b] -> FreeGroup b
forall a. [Either a a] -> FreeGroup a
FreeGroup ([Either b b] -> FreeGroup b) -> [Either b b] -> FreeGroup b
forall a b. (a -> b) -> a -> b
$ (Either a a -> Either b b) -> [Either a a] -> [Either b b]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((a -> b) -> (a -> b) -> Either a a -> Either b b
forall (p :: * -> * -> *) a b c d.
Bifunctor p =>
(a -> b) -> (c -> d) -> p a c -> p b d
bimap a -> b
f a -> b
f) [Either a a]
g

instance Applicative FreeGroup where
    pure :: a -> FreeGroup a
pure a
a = [Either a a] -> FreeGroup a
forall a. [Either a a] -> FreeGroup a
FreeGroup ([Either a a] -> FreeGroup a) -> [Either a a] -> FreeGroup a
forall a b. (a -> b) -> a -> b
$ Either a a -> [Either a a]
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Either a a -> [Either a a]) -> Either a a -> [Either a a]
forall a b. (a -> b) -> a -> b
$ a -> Either a a
forall (f :: * -> *) a. Applicative f => a -> f a
pure a
a
    <*> :: FreeGroup (a -> b) -> FreeGroup a -> FreeGroup b
(<*>) = FreeGroup (a -> b) -> FreeGroup a -> FreeGroup b
forall (m :: * -> *) a b. Monad m => m (a -> b) -> m a -> m b
ap

instance Monad FreeGroup where
    return :: a -> FreeGroup a
return = a -> FreeGroup a
forall (f :: * -> *) a. Applicative f => a -> f a
pure
    (FreeGroup [Either a a]
g) >>= :: FreeGroup a -> (a -> FreeGroup b) -> FreeGroup b
>>= a -> FreeGroup b
f = [Either b b] -> FreeGroup b
forall a. [Either a a] -> FreeGroup a
FreeGroup ([Either b b] -> FreeGroup b) -> [Either b b] -> FreeGroup b
forall a b. (a -> b) -> a -> b
$ (Either a a -> [Either b b]) -> [Either a a] -> [Either b b]
forall (t :: * -> *) a b. Foldable t => (a -> [b]) -> t a -> [b]
concatMap Either a a -> [Either b b]
go [Either a a]
g
        where
          go :: Either a a -> [Either b b]
go (Left a
a)  = FreeGroup b -> [Either b b]
forall a. FreeGroup a -> [Either a a]
runFreeGroup (FreeGroup b -> [Either b b]) -> FreeGroup b -> [Either b b]
forall a b. (a -> b) -> a -> b
$ FreeGroup b -> FreeGroup b
forall m. Group m => m -> m
invert (a -> FreeGroup b
f a
a)
          go (Right a
a) = FreeGroup b -> [Either b b]
forall a. FreeGroup a -> [Either a a]
runFreeGroup (FreeGroup b -> [Either b b]) -> FreeGroup b -> [Either b b]
forall a b. (a -> b) -> a -> b
$ a -> FreeGroup b
f a
a

instance Alternative FreeGroup where
    empty :: FreeGroup a
empty = FreeGroup a
forall a. Monoid a => a
mempty
    <|> :: FreeGroup a -> FreeGroup a -> FreeGroup a
(<|>) = FreeGroup a -> FreeGroup a -> FreeGroup a
forall a. Semigroup a => a -> a -> a
(<>)

-- | /O(n)/ Simplifies a word in a free group.
--
-- === __Examples:__
--
-- >>> simplify $ FreeGroup [Right 'a', Left 'b', Right 'c', Left 'c', Right 'b', Right 'a']
-- FreeGroup {runFreeGroup = [Right 'a',Right 'a']}
--
simplify :: (Eq a) => FreeGroup a -> FreeGroup a
simplify :: FreeGroup a -> FreeGroup a
simplify (FreeGroup [Either a a]
g) = [Either a a] -> FreeGroup a
forall a. [Either a a] -> FreeGroup a
FreeGroup ([Either a a] -> FreeGroup a) -> [Either a a] -> FreeGroup a
forall a b. (a -> b) -> a -> b
$ (Either a a -> [Either a a] -> [Either a a])
-> [Either a a] -> [Either a a] -> [Either a a]
forall (t :: * -> *) a b.
Foldable t =>
(a -> b -> b) -> b -> t a -> b
foldr Either a a -> [Either a a] -> [Either a a]
forall a. Eq a => Either a a -> [Either a a] -> [Either a a]
go [] [Either a a]
g
    where
      go :: Either a a -> [Either a a] -> [Either a a]
go (Left a
a) ((Right a
a'):[Either a a]
as) | a
a a -> a -> Bool
forall a. Eq a => a -> a -> Bool
== a
a' = [Either a a]
as
      go (Right a
a) ((Left a
a'):[Either a a]
as) | a
a a -> a -> Bool
forall a. Eq a => a -> a -> Bool
== a
a' = [Either a a]
as
      go Either a a
a [Either a a]
as = Either a a
aEither a a -> [Either a a] -> [Either a a]
forall a. a -> [a] -> [a]
:[Either a a]
as

-- | /O(n)/ Interpret a word in a free group over some group @g@ as an element in a group @g@.
--
interpret :: (Group g) => FreeGroup g -> g
interpret :: FreeGroup g -> g
interpret (FreeGroup [Either g g]
g) = (Either g g -> g -> g) -> g -> [Either g g] -> g
forall (t :: * -> *) a b.
Foldable t =>
(a -> b -> b) -> b -> t a -> b
foldr Either g g -> g -> g
forall a. Group a => Either a a -> a -> a
go g
forall a. Monoid a => a
mempty [Either g g]
g
    where
      go :: Either a a -> a -> a
go (Left a
a) a
acc  = a -> a
forall m. Group m => m -> m
invert a
a a -> a -> a
forall a. Semigroup a => a -> a -> a
<> a
acc
      go (Right a
a) a
acc = a
a a -> a -> a
forall a. Semigroup a => a -> a -> a
<> a
acc

-- | /O(n)/ Strict variant of 'interpret'.
--
interpret' :: (Group g) => FreeGroup g -> g
interpret' :: FreeGroup g -> g
interpret' (FreeGroup [Either g g]
g) = (g -> Either g g -> g) -> g -> [Either g g] -> g
forall (t :: * -> *) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
foldl' g -> Either g g -> g
forall a. Group a => a -> Either a a -> a
go g
forall a. Monoid a => a
mempty [Either g g]
g
    where
      go :: a -> Either a a -> a
go a
acc (Left a
a) = a
acc a -> a -> a
forall a. Semigroup a => a -> a -> a
<> a -> a
forall m. Group m => m -> m
invert a
a
      go a
acc (Right a
a) = a
acc a -> a -> a
forall a. Semigroup a => a -> a -> a
<> a
a

-- | Present a 'Group' as a 'FreeGroup' modulo relations.
--
present :: Group g => FreeGroup g -> (FreeGroup g -> g) -> g
present :: FreeGroup g -> (FreeGroup g -> g) -> g
present = ((FreeGroup g -> g) -> FreeGroup g -> g)
-> FreeGroup g -> (FreeGroup g -> g) -> g
forall a b c. (a -> b -> c) -> b -> a -> c
flip (FreeGroup g -> g) -> FreeGroup g -> g
forall a b. (a -> b) -> a -> b
($)
{-# inline present #-}

-- -------------------------------------------------------------------- --
-- Free abelian groups

-- | /O(n)/ Constructs a 'Data.Group.Free.FreeAbelianGroup' from a finite 'Map' from
-- the set of generators (@a@) to its multiplicities.
mkFreeAbelianGroup :: Ord a => Map a Integer -> FreeAbelianGroup a
mkFreeAbelianGroup :: Map a Integer -> FreeAbelianGroup a
mkFreeAbelianGroup = Map a Integer -> FreeAbelianGroup a
forall a. Map a Integer -> FreeAbelianGroup a
MkFreeAbelianGroup (Map a Integer -> FreeAbelianGroup a)
-> (Map a Integer -> Map a Integer)
-> Map a Integer
-> FreeAbelianGroup a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Integer -> Bool) -> Map a Integer -> Map a Integer
forall a k. (a -> Bool) -> Map k a -> Map k a
Map.filter (Integer -> Integer -> Bool
forall a. Eq a => a -> a -> Bool
/= Integer
0)

-- | /O(1)/ Gets a representation of 'Data.Group.Free.FreeAbelianGroup' as
-- 'Map'. The returned map contains no records with
-- multiplicity @0@ i.e. @'Map.lookup' a@ on the returned map
-- never returns @Just 0@.
--
runFreeAbelianGroup :: FreeAbelianGroup a -> Map a Integer
runFreeAbelianGroup :: FreeAbelianGroup a -> Map a Integer
runFreeAbelianGroup (MkFreeAbelianGroup Map a Integer
g) = Map a Integer
g

-- NOTE: We can't implement Functor/Applicative/Monad here
-- due to the Ord constraint. C'est La Vie!

-- | Given a function from generators to an abelian group @g@,
-- lift that function to a group homomorphism from 'Data.Group.Free.FreeAbelianGroup' to @g@.
--
-- In other words, it's a function analogus to 'foldMap' for 'Monoid' or
-- 'Data.Group.Foldable.goldMap' for @Group@.
--
abfoldMap :: (Abelian g) => (a -> g) -> FreeAbelianGroup a -> g
abfoldMap :: (a -> g) -> FreeAbelianGroup a -> g
abfoldMap a -> g
f = (g -> a -> Integer -> g) -> g -> Map a Integer -> g
forall a k b. (a -> k -> b -> a) -> a -> Map k b -> a
Map.foldlWithKey' g -> a -> Integer -> g
forall x. Integral x => g -> a -> x -> g
step g
forall a. Monoid a => a
mempty (Map a Integer -> g)
-> (FreeAbelianGroup a -> Map a Integer) -> FreeAbelianGroup a -> g
forall b c a. (b -> c) -> (a -> b) -> a -> c
. FreeAbelianGroup a -> Map a Integer
forall a. FreeAbelianGroup a -> Map a Integer
runFreeAbelianGroup
  where
    step :: g -> a -> x -> g
step g
g a
a x
n = g
g g -> g -> g
forall a. Semigroup a => a -> a -> a
<> g -> x -> g
forall m x. (Group m, Integral x) => m -> x -> m
pow (a -> g
f a
a) x
n

-- | Functorial 'fmap' for a 'Data.Group.Free.FreeAbelianGroup'.
--
-- === __Examples__:
--
-- >>> singleton 'a' <> singleton 'A'
-- FreeAbelianGroup $ fromList [('A',1),('a',1)]
-- >>> import Data.Char (toUpper)
-- >>> abmap toUpper $ singleton 'a' <> singleton 'A'
-- FreeAbelianGroup $ fromList [('A',2)]
--
abmap :: (Ord b) => (a -> b) -> FreeAbelianGroup a -> FreeAbelianGroup b
abmap :: (a -> b) -> FreeAbelianGroup a -> FreeAbelianGroup b
abmap a -> b
f = (a -> FreeAbelianGroup b)
-> FreeAbelianGroup a -> FreeAbelianGroup b
forall g a. Abelian g => (a -> g) -> FreeAbelianGroup a -> g
abfoldMap (b -> FreeAbelianGroup b
forall a. a -> FreeAbelianGroup a
singleton (b -> FreeAbelianGroup b) -> (a -> b) -> a -> FreeAbelianGroup b
forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> b
f)

-- | Lift a singular value into a 'Data.Group.Free.FreeAbelianGroup'. Analogous to 'pure'.
--
-- === __Examples__:
--
-- >>> singleton "foo"
-- FreeAbelianGroup $ fromList [("foo",1)]
--
singleton :: a -> FreeAbelianGroup a
singleton :: a -> FreeAbelianGroup a
singleton a
a = Map a Integer -> FreeAbelianGroup a
forall a. Map a Integer -> FreeAbelianGroup a
MkFreeAbelianGroup (Map a Integer -> FreeAbelianGroup a)
-> Map a Integer -> FreeAbelianGroup a
forall a b. (a -> b) -> a -> b
$ a -> Integer -> Map a Integer
forall k a. k -> a -> Map k a
Map.singleton a
a Integer
1

-- | Monadic 'join' for a 'Data.Group.Free.FreeAbelianGroup'.
--
abjoin :: (Ord a) => FreeAbelianGroup (FreeAbelianGroup a) -> FreeAbelianGroup a
abjoin :: FreeAbelianGroup (FreeAbelianGroup a) -> FreeAbelianGroup a
abjoin = FreeAbelianGroup (FreeAbelianGroup a) -> FreeAbelianGroup a
forall g. Abelian g => FreeAbelianGroup g -> g
abInterpret

-- | Interpret a free group as a word in the underlying group @g@.
--
abInterpret :: (Abelian g) => FreeAbelianGroup g -> g
abInterpret :: FreeAbelianGroup g -> g
abInterpret = (g -> g) -> FreeAbelianGroup g -> g
forall g a. Abelian g => (a -> g) -> FreeAbelianGroup a -> g
abfoldMap g -> g
forall a. a -> a
id

-- | Bidirectional pattern synonym for the construction of
-- 'Data.Group.Free.Internal.FreeAbelianGroup's.
--
pattern FreeAbelianGroup :: Ord a => Map a Integer -> FreeAbelianGroup a
pattern $bFreeAbelianGroup :: Map a Integer -> FreeAbelianGroup a
$mFreeAbelianGroup :: forall r a.
Ord a =>
FreeAbelianGroup a -> (Map a Integer -> r) -> (Void# -> r) -> r
FreeAbelianGroup g <- MkFreeAbelianGroup g where
    FreeAbelianGroup Map a Integer
g = Map a Integer -> FreeAbelianGroup a
forall a. Ord a => Map a Integer -> FreeAbelianGroup a
mkFreeAbelianGroup Map a Integer
g
{-# complete FreeAbelianGroup #-}