The genie Reference Manual

Table of Contents

The genie Reference Manual

This is the genie Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:52:24 2018 GMT+0.

1 Introduction

genie

A simple wrapper to generate portably seedable pseudo-random numbers.

Overview

This library allows you to generate random numbers, with a portable and seedable generator. This means that a generator initialized with a particular seed will yield the same sequence of generated numbers on every Common Lisp implementation.

Install

(ql:quickload :genie)

Usage

To generate a random number, you first need to create a generator object seeded with an integer:

(make-generator 123)

Alternatively, you can leave out the seed, to have one generated for you:

(make-generator)

The above will print a log message with the generator's seed value:

[INFO ] [2016-12-07 23:51:29] Random seed: 123258810179538

Once you have a generator, we can use the GEN function to generate a number. There are a few different methods to use for generating a number.

Generate a boolean value (T or NIL)

To generate a boolean, supply the :BOOL keyword to GEN, optionally with a probability for true:

(let ((generator (make-generator)))
  (gen :bool generator :probability 0.9))

The above will generate T 90% of the time, and NIL otherwise.

Generate a floating-point number within a range

To generate a number that falls within a range, supply the :RANGE keyword to GEN like so:

(let ((generator (make-generator)))
  (gen :range generator :min 0.0 :max 1.0))

The above will generate a floating-point number between 0 and 10.

Generate an integer

To generate an integer within a range, supply the :INT keyword to GEN:

(let ((generator (make-generator)))
  (gen :int generator :min 1 :max 100))

The above will generate an integer between 1 and 100, both inclusive. You may also tell it to generate an odd or an even integer within this range, by using the :PARITYP keyword as such:

(let ((generator (make-generator)))
  (gen :int generator :min 1 :max 100 :parityp t))

This will generate an odd integer between 1 and 100. The value of :MIN determines the parity of the result - a value of 2 for :MIN would generate an even number between 2 and 100.

Choose a random element from a sequence

To choose a random element from a list or other sequence, supply the :ELT keyword to GEN:

(let ((generator (make-generator))
      (some-sequence '(1 2 3)))
  (gen :elt generator :sequence some-sequence))

The above will choose a random element from the sequence given.

License

Copyright © 2016-2018 Michael Fiano.

Licensed under the MIT License.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 genie

Maintainer

Michael Fiano <mail@michaelfiano.com>

Author

Michael Fiano <mail@michaelfiano.com>

Home Page

https://www.michaelfiano.com/projects/genie

Source Control

(:git "git@github.com:mfiano/genie.git")

Bug Tracker

https://github.com/mfiano/genie/issues

License

MIT

Description

A simple wrapper to generate portably seedable pseudo-random numbers.

Long Description

# genie

A simple wrapper to generate portably seedable pseudo-random numbers.

## Overview

This library allows you to generate random numbers, with a portable and seedable generator. This means that a generator initialized with a particular seed will yield the same sequence of generated numbers on every Common Lisp implementation.

## Install

“‘ lisp
(ql:quickload :genie)
“‘

## Usage

To generate a random number, you first need to create a generator object seeded with an integer:

“‘ lisp
(make-generator 123)
“‘

Alternatively, you can leave out the seed, to have one generated for you:

“‘ lisp
(make-generator)
“‘

The above will print a log message with the generator’s seed value:

“‘
[INFO ] [2016-12-07 23:51:29] Random seed: 123258810179538
“‘

Once you have a generator, we can use the ‘GEN‘ function to generate a number. There are a few different methods to use for generating a number.

### Generate a boolean value (T or NIL)

To generate a boolean, supply the ‘:BOOL‘ keyword to ‘GEN‘, optionally with a probability for true:

“‘ lisp
(let ((generator (make-generator)))
(gen :bool generator :probability 0.9))
“‘

The above will generate ‘T‘ 90% of the time, and ‘NIL‘ otherwise.

### Generate a floating-point number within a range

To generate a number that falls within a range, supply the ‘:RANGE‘ keyword to ‘GEN‘ like so:

“‘ lisp
(let ((generator (make-generator)))
(gen :range generator :min 0.0 :max 1.0))
“‘

The above will generate a floating-point number between 0 and 10.

### Generate an integer

To generate an integer within a range, supply the ‘:INT‘ keyword to ‘GEN‘:

“‘ lisp
(let ((generator (make-generator)))
(gen :int generator :min 1 :max 100))
“‘

The above will generate an integer between 1 and 100, both inclusive. You may also tell it to generate an odd or an even integer within this range, by using the ‘:PARITYP‘ keyword as such:

“‘ lisp
(let ((generator (make-generator)))
(gen :int generator :min 1 :max 100 :parityp t))
“‘

This will generate an odd integer between 1 and 100. The value of ‘:MIN‘ determines the parity of the result - a value of 2 for ‘:MIN‘ would generate an even number between 2 and 100.

### Choose a random element from a sequence

To choose a random element from a list or other sequence, supply the ‘:ELT‘ keyword to ‘GEN‘:

“‘ lisp
(let ((generator (make-generator))
(some-sequence ’(1 2 3)))
(gen :elt generator :sequence some-sequence))
“‘

The above will choose a random element from the sequence given.

## License

Copyright © 2016-2018 [Michael Fiano](mailto:mail@michaelfiano.com).

Licensed under the MIT License.

Version

1.0.0

Dependencies

• cl-variates
• simple-logger

Source

genie.asd (file)

Components

• package.lisp (file)
• genie.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 genie.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/genie-20180228-git/genie.asd

Systems

genie (system)

3.1.2 genie/package.lisp

Parent

genie (system)

Location

package.lisp

Packages

genie

3.1.3 genie/genie.lisp

Dependency

package.lisp (file)

Parent

genie (system)

Location

genie.lisp

Exported Definitions

• gen (generic function)
• gen (method)
• gen (method)
• gen (method)
• gen (method)
• make-generator (function)
• make-seed (function)

4 Packages

Packages are listed by definition order.

4.1 genie

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• gen (generic function)
• gen (method)
• gen (method)
• gen (method)
• gen (method)
• make-generator (function)
• make-seed (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: make-generator &optional SEED

Create a random number generator object, using SEED to initialize it. If SEED is not supplied, a new seed will be generated.

Package

genie

Source

genie.lisp (file)

Function: make-seed ()

Compute a seed to be given to a generator.

Package

genie

Source

genie.lisp (file)

5.1.2 Generic functions

Generic Function: gen KIND GENERATOR &key SEQUENCE MIN MAX PARITYP PROBABILITY

Generate a random number of a certain kind.

Package

genie

Source

genie.lisp (file)

Methods

Method: gen (KIND (eql elt)) GENERATOR &key SEQUENCE

Randomly select an element from SEQUENCE.

Method: gen (KIND (eql int)) GENERATOR &key MIN MAX PARITYP

Generate an integer between MIN and MAX (inclusive). If PARITYP is non-nil, generate an even number if MIN is even, or an odd number if MIN is odd.

Method: gen (KIND (eql range)) GENERATOR &key MIN MAX

Generate a number between MIN and MAX.

Method: gen (KIND (eql bool)) GENERATOR &key PROBABILITY

Generate a true or false value, with the given PROBABILITY for true.

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types