diff --git a/INSTALL b/INSTALL deleted file mode 100644 --- a/INSTALL +++ /dev/null @@ -1,125 +0,0 @@ -logfloat-0.12 -============= - -In general, logfloat is a simple package and should be easy to -install. The specifics are a bit murky however, since we use CPP -and the FFI and want to retain portability, and due to the rapid -evolution of Cabal and other development tools. This document will -walk you through the ins and outs for all supported configurations. - -If you run into issues about missing or similar, then see -the FFI Problems section. If you want to compile Haddock documentation, -then see that section. - - -Building for GHC (6.8 and above) -================================ - -Installation under GHC is simple using the standard Cabal build -loop: - - runhaskell Setup.hs configure - runhaskell Setup.hs build - runhaskell Setup.hs copy - runhaskell Setup.hs register - -The logfloat package is no longer supported for GHC 6.6, though it -could probably be made to work with it by changing LANGUAGE pragma -into the appropriate OPTIONS_GHC equivalents. Since it's not supported -anymore, more significant changes may have become necessary as well. - - -Building for Hugs (September 2006) -================================== - -Installation under Hugs is unfortunately more complicated due to -some option-passing bugs in Cabal. You should be able to build -things with these modifications to the usual Cabal build loop: - - runhaskell Setup.hs configure --hugs \ - --with-cpphs="`which cpphs-hugs`" \ - --ffihugs-options="-98 +o" \ - --ffihugs-option=-F'cpp -P -traditional -D__HUGS__=200609 -D__USE_FFI__' - runhaskell Setup.hs build - runhaskell Setup.hs copy - runhaskell Setup.hs register - -Hugs installs cpphs under the name "cpphs-hugs" by default. The -`which` command will try to resolve the location, assuming it's on -your $PATH. If it isn't, then change the --with-cpphs= flag to point -to where cpphs is installed on your system. - -Some additional details about difficulties with building -for Hugs can be found in this blog post and the bug reports: - - http://winterkoninkje.livejournal.com/60707.html - http://hackage.haskell.org/trac/hackage/ticket/526 - http://hackage.haskell.org/trac/hackage/ticket/527 - -And while previous versions of Cabal could build this package (with -the above commandline to work around those bugs), Hugs support is -broken in Cabal 1.8 (including at least 1.8.0.2 through 1.8.0.6): - - http://hackage.haskell.org/trac/hackage/ticket/633 - - -FFI Problems -============ - -The logfloat package uses the FFI to access functions in libm to -improve accuracy. These functions are part of the ISO C 1999 standard -and are supported on most systems, however they're not part of the -ANSI C standard nor the System V standard and so they might be -unavailable on some systems. If you encounter errors during build -about not being able to find , not having prototypes for -functions, or linking errors, then you are probably on such a system. - -In order to use pure Haskell and disable the FFI, pass -f-useFFI -during the configure phase to disable the useFFI flag. (If compiling -for Hugs, also be sure *not* to pass -D__USE_FFI__ to the cpp filter -for ffihugs.) This will degrade the accuracy of certain operations, -but should still compile cleanly. - -If you run into errors like "error: 'log1p' redeclared as different -kind of symbol" this is due to a bug in GHC 6.10.1 where you can't -use both -fvia-C and the FFI. This bug should be circumvented for -the moment, but resolving it is still a work in progress. See the -bug report (which is resolved in GHC 6.10.2): - - http://hackage.haskell.org/trac/ghc/ticket/3117 - - -Windows FFI -=========== - -The logfloat package builds and installs cleanly on Windows XP using -GHC 6.10.1 (without needing Cygwin nor Mingw/Msys). The C functions -reside in libmingwex.a which is bundled with GHC on WinXP. - -However, it does not work from the GHCi debugger and gives errors -like "can't load .so/.DLL for: m (addDLL: could not load DLL)". If -you know how to fix this issue or have further details on Windows -compatability, please contact the maintainer. - - -Haddock Documentation -===================== - -In Cabal 1.2 there is a bug in the handling of building Haddock -documentation when CPP is involved. These issues have been fixed -in Cabal 1.6, but here are the instructions if you're on older -systems. - -In Cabal 1.2 the cpp-options field is not passed to Haddock, and -therefore any macros defined there are not seen, which can cause -Haddock to fail. The old workaround was to define CPP macros in the -ghc-options field which *does* get passed to Haddock. This is now -considered bad style and is forbidden by Hackage. It appears that -passing --haddock-option=... or --ghc-option=... flags during -configure does not have the same effect as defining the field. - -Therefore, in order to properly compile Haddock documentation on -Cabal 1.2, you should go into logfloat.cabal and uncomment the -ghc-options fields which declare CPP macros -D__USE_FFI__ and --D__HUGS__=200609. If you know of a better workaround for this -configuration, contact the maintainer. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,261 @@ +logfloat +======== +[![Hackage version](https://img.shields.io/hackage/v/logfloat.svg?style=flat)](https://hackage.haskell.org/package/logfloat) +[![Hackage-Deps](https://img.shields.io/hackage-deps/v/logfloat.svg?style=flat)](http://packdeps.haskellers.com/specific?package=logfloat) +[![TravisCI Build Status](https://img.shields.io/travis/wrengr/logfloat.svg?style=flat)](https://travis-ci.org/wrengr/logfloat) +[![CircleCI Build Status](https://circleci.com/gh/wrengr/logfloat.svg?style=shield&circle-token=b57517657c556be6fd8fca92b843f9e4cffaf8d1)](https://circleci.com/gh/wrengr/logfloat) + +This package provides a type for storing numbers in the log-domain, +primarily useful for preventing underflow when multiplying many +probabilities as in HMMs and other probabilistic models. The package +also provides modules for dealing with floating numbers correctly. + +As of version 0.13.3, we've dropped support for Hugs and GHC < 7.8. +Nothing major has changed, so they should still work; it's just +that they're no longer officially supported. (In practice, GHC 7.6 +still works just fine, and is still being tested against. It's just +that this support will be droped in the future, once it becomes a +burden.) Thus, this version of the library provides a transitional +point between backwards compatability and adding new features (see +below). + +Note that the GitHub repository is just a clone of [the Darcs +repo](http://code.haskell.org/~wren/logfloat/). I'm testing out +whether to switch things over to GitHub in order to use TravisCI, +and an official ticket tracker, etc. + + +## Install + +In general, this is a simple package and should be easy to install. +The specifics are a bit murky however, since we use CPP and the FFI +and want to retain portability, and due to the rapid evolution of +Cabal and other development tools. You should be able to use one +of the following standard installation methods: + + -- With cabal-install and without the source: + $> cabal install logfloat + + -- With cabal-install and with the source already: + $> cd logfloat + $> cabal install + + -- Without cabal-install, but with the source already: + $> cd logfloat + $> runhaskell Setup.hs configure --user + $> runhaskell Setup.hs build + $> runhaskell Setup.hs haddock --hyperlink-source + $> runhaskell Setup.hs copy + $> runhaskell Setup.hs register + +The Haddock step is optional. + + +### FFI Problems + +The logfloat package uses the FFI to access functions in libm to +improve accuracy. These functions are part of the ISO C 1999 standard +and are supported on most systems, however they're not part of the +ANSI C standard nor the System V standard and so they might be +unavailable on some systems. If you encounter errors during build +about not being able to find ``, not having prototypes for +functions, or linking errors, then you are probably on such a system. + +In order to use pure Haskell and disable the FFI, pass -f-useFFI +during the configure phase to disable the useFFI flag. This will +degrade the accuracy of certain operations, but should still compile +cleanly. + +If you run into errors like "error: 'log1p' redeclared as different +kind of symbol" this is due to a bug in GHC 6.10.1 where you can't +use both -fvia-C and the FFI. This bug should be circumvented for +the moment, but resolving it is still a work in progress. See the +bug report (which is resolved in GHC 6.10.2): + + http://hackage.haskell.org/trac/ghc/ticket/3117 + + +### Windows FFI + +The logfloat package builds and installs cleanly with GHC on Windows +(without needing Cygwin nor Mingw/Msys), and the installed package +can be used in compiled programs without any issues. + +However, by default, the package does not work from the GHCi debugger +and gives errors like "can't load .so/.DLL for: m (addDLL: could +not load DLL)". This is a long-standing issue with GHCi having to +do with the fact that, on Windows, the so-called "libm" file does +not actually contain anything (as it does on POSIX) and the C +functions we use are instead placed in `libmingwex.a` (which comes +bundled with GHC). The problem is that `ghc` (the compiler) knows +to pull in `libmingwex.a`, whereas `ghci` (the interactive debugger) +does not. All of this is true at least as far back as Windows XP +and GHC 6.10.1. Some more information can be found in the ticket: + + https://ghc.haskell.org/trac/ghc/ticket/3242 + +The most reliable workaround at this point, alas, is to compile the +library with FFI support disabled in order to be able to use it in +GHCi, and then to recompile with FFI enabled whenever you need to +ship a compiled program. + +A less-reliable workaround (i.e., needs to be tailored for your +system based on your paths, and you'll need to have `gcc` installed) +which avoids the need for recompilation is to generate the DLL +yourself by running the following two commands and then placing the +resulting `m.dll` into your path. + + ar -x libmingwex.a + gcc -shared *.o -o m.dll + + +### Testing + +If you want to run the test suite, use the following standard method +(with `runhaskell Setup.hs` in lieu of `cabal`, if necessary): + + $> cd logfloat + $> cabal configure --enable-tests --enable-coverage + $> cabal build + $> cabal test --keep-tix-files + +The results of the code coverage are in +`./dist/hpc/vanilla/html/logfloat-$VERSION/hpc_index.html`. If +you're not interested in the coverage of the test suite, then you +needn't pass the `--enable-coverage` nor `--keep-tix-files` flags. +Note that older versions of cabal used the flag name +`--enable-library-coverage` instead of `--enable-coverage`. And +IIRC hpc integration in cabal was broken for ghc-7.6. + + +### Haddock Problems + +In Cabal 1.2 there is a bug in the handling of building Haddock +documentation when CPP is involved. These issues have been fixed +in Cabal 1.6, but here are the instructions if you're on older +systems. + +In Cabal 1.2 the cpp-options field is not passed to Haddock, and +therefore any macros defined there are not seen, which can cause +Haddock to fail. The old workaround was to define CPP macros in the +ghc-options field which *does* get passed to Haddock. This is now +considered bad style and is forbidden by Hackage. It appears that +passing --haddock-option=... or --ghc-option=... flags during +configure does not have the same effect as defining the field. + +Therefore, in order to properly compile Haddock documentation on +Cabal 1.2, you should go into logfloat.cabal and uncomment the +ghc-options fields which declare CPP macros -D__USE_FFI__ and +-D__HUGS__=200609. If you know of a better workaround for this +configuration, contact the maintainer. + + +### Building for Hugs (September 2006) + +If you're feeling adventurous and want to try and get the library +to compile under Hugs, here's how you used to be able to compile +things: + + runhaskell Setup.hs configure --hugs \ + --with-cpphs="`which cpphs-hugs`" \ + --ffihugs-options="-98 +o" \ + --ffihugs-option=-F'cpp -P -traditional -D__HUGS__=200609 -D__USE_FFI__' + runhaskell Setup.hs build + runhaskell Setup.hs copy + runhaskell Setup.hs register + +If you need to disable the FFI due to issues with not being able +to find , not having prototypes for functions, or linking +errors, be sure *not* to pass -D__USE_FFI__ to the cpp filter for +ffihugs. + +Notably, Hugs installs cpphs under the name "cpphs-hugs" by default. +The `which` command will try to resolve the location, assuming it's +on your $PATH. If it isn't, then change the --with-cpphs= flag to +point to where cpphs is installed on your system. + +Some additional details about difficulties with building for Hugs +can be found in this blog post and the bug reports: + + http://winterkoninkje.livejournal.com/60707.html + http://hackage.haskell.org/trac/hackage/ticket/526 + http://hackage.haskell.org/trac/hackage/ticket/527 + +And while previous versions of Cabal could build this package (with +the above commandline to work around those bugs), Hugs support is +broken in Cabal 1.8 (including at least 1.8.0.2 through 1.8.0.6): + + http://hackage.haskell.org/trac/hackage/ticket/633 + + +## Changes: Version 0.13.3+ (2015-03-29) vs 0.12.1 (2010-03-19) + +* Monomorphized `logFloat`, `logToLogFloat`, `fromLogFloat`, and +`logFromLogFloat`: that is, they all take/return `Double` now. The +change was made to help reduce the need for explicit type signatures. +It shouldn't really affect most users, since it seems noone was +really making use of the polymorphism provided by previous versions. +To get the previous behavior back, just explicitly add calls to +`realToFrac` wherever necessary. + +* Fixed some instances to get them to compile under the new role-based +type system of GHC 7.10 + +* Cleaned up various extraneous rewrite rules, specializations, etc + +* Added the functions `sum`, `product`, and `pow`. Both sum and +product preserve more precision than the fold-based definitions in +the Prelude. Moreover, sum is *much* faster than the Prelude version, +since it only requires crossing the log/exp boundary n+1 times, +instead of 2\*(n-1) times. The only downside is that sum requires +two passes over the input and thus is not amenable to list fusion. + +* (Version 0.13.3.2; 2015-08-06) Fixed the `Show LogFloat` instance +to produce parentheses in the right place. + + +## Upcoming changes (0.14+) + +* Since the `Data.Number.RealToFrac` module is no longer required +by any of the others, it will probably be forked off to a separate +package in order to improve portability of the rest of the package +by removing the need for MPTCs. + +* There's long been clamoring for adding a +vector:`Data.Vector.Unboxed.Unbox` instance. I've been reluctant +to add such an instance due to wanting to retain backwards compatibility +and portability. Having dropped support for Hugs and older versions +of GHC, I'm now willing to add them in. + +The logfloat library is conceptually quite simple, and thus to +whatever extent possible I'd still like to retain portability to +non-GHC compilers. So if you are interested in using logfloat with +another compiler/interpreter but run into problems (e.g., due to +the type families required by the vector library), please get in +touch and I'll try to get things to work. + + +## Compatibility / Portability + +The package is compatible with GHC 7.8.3 and 7.10.1. It may still +compile with older versions of GHC (or even Hugs!), however they +are no longer officially supported. + +The package is not compatible with nhc98 and Yhc because +`Data.Number.RealToFrac` uses MPTCs. However, that module is no +longer required by any others, and all the other modules should be +compatible with these compilers. Thus, it should be fairly easy to +port. If you do so, please let me know and I'll try to incorporate +support for them. + + +## Links + +* [Website](http://cl.indiana.edu/~wren/) +* [Blog](http://winterkoninkje.dreamwidth.org/) +* [Twitter](https://twitter.com/wrengr) +* [Hackage](http://hackage.haskell.org/package/logfloat) +* [Darcs](http://code.haskell.org/~wren/logfloat) +* [GitHub (clone)](https://github.com/wrengr/logfloat) +* [Haddock (Darcs version) + ](http://code.haskell.org/~wren/logfloat/dist/doc/html/logfloat) diff --git a/logfloat.cabal b/logfloat.cabal --- a/logfloat.cabal +++ b/logfloat.cabal @@ -1,14 +1,16 @@ ---------------------------------------------------------------- --- wren gayle romano ~ 2015.08.06 +-- wren gayle romano ~ 2015.10.02 ---------------------------------------------------------------- --- By and large Cabal >=1.2 is fine; but >= 1.6 gives tested-with: --- and source-repository:. -Cabal-Version: >= 1.6 +-- By and large Cabal >=1.2 is fine; but +-- * >=1.6 gives tested-with: and source-repository: +-- * >=1.8 allows executables to build-depends: on the library +-- * >=1.9.2 allows Test-Suite +Cabal-Version: >= 1.9.2 Build-Type: Simple Name: logfloat -Version: 0.13.3.2 +Version: 0.13.3.3 Stability: experimental Homepage: http://code.haskell.org/~wren/ Author: wren gayle romano @@ -18,19 +20,24 @@ License-File: LICENSE Category: Data, Math, Natural Language Processing, Statistics -Synopsis: Log-domain floating point numbers -Description: This module presents a type for storing numbers - in the log-domain. The main reason for doing this - is to prevent underflow when multiplying many - probabilities as is done in Hidden Markov Models. - It is also helpful for preventing overflow. +Synopsis: + Log-domain floating point numbers +Description: + This module presents a type for storing numbers in the log-domain. + The main reason for doing this is to prevent underflow when + multiplying many probabilities as is done in Hidden Markov + Models. It is also helpful for preventing overflow. +Extra-source-files: + README.md, CHANGELOG --- TODO: does GHC 6.12.1 and 7.6.1 still work? do we care? +-- Cf., Tested-With: - GHC == 7.8.3, GHC == 7.10.1 -Extra-source-files: - INSTALL, CHANGELOG + GHC ==7.6.1, GHC ==7.6.2, GHC ==7.6.3, + GHC ==7.8.1, GHC ==7.8.2, GHC ==7.8.3, GHC ==7.8.4, + GHC ==7.10.1, GHC ==7.10.2 + +---------------------------------------------------------------- Source-Repository head Type: darcs Location: http://community.haskell.org/~wren/logfloat @@ -38,9 +45,10 @@ ---------------------------------------------------------------- Flag useFFI Default: True - Description: Use FFI to link C's log1p. Improves accuracy and - same performance. Disable only if your compiler - doesn't support FFI. + Description: + Use FFI to link C's log1p. Improves accuracy while maintaining + the same performance. Disable only if your compiler doesn't + support FFI. ---------------------------------------------------------------- Library @@ -51,7 +59,7 @@ , Data.Number.PartialOrd , Hugs.RealFloat - Build-Depends: base == 4.* + Build-Depends: base >= 4.6 && < 5 -- TODO: do we need any version constraints on array? , array