Skip to content

Commit

Permalink
Fix up rst file for PyPi
Browse files Browse the repository at this point in the history
  • Loading branch information
@caraneilwarner
caraneilwarner committed Apr 2, 2018
1 parent 358ba73 commit 5918e0a
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 64 deletions.
138 changes: 75 additions & 63 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Pantheon Generator
==================
Pantheon Generator
==================

This library procedurally generates `Gods` with internally-coherent domains,
and `Pantheons` comprising generations of `Gods` that feel related to one
Expand All @@ -12,82 +14,92 @@ metaphor of sexual reproduction:
* **Asexual reproduction** occurs when a user generates a `God` from two strings.
* **Sexual reproduction** occurs when a user generates a `Pantheon` from two `Gods`.

### How to Use the Library
Generate individual `Gods` with seeder words:

The user selects two seed words and uses them to generate a `God`:
`God("milk","honey")`

> God("hunting", "art")
Generate `Pantheons` with two `God` objects:

The result is Chetan, God of Illustrators, Prints, and Drawings. The user does
this a second time:
`Pantheon(God, God)`

> God("agriculture", "science")
*Note*: `Gods` have chromosomes and you must have an XX and an XY to spawn a Pantheon.
That said, gender != chromosomes so it is possible to have two fathers of creation, or
two mothers of creation, or non-binary divine beings as the parents of your pantheon.

The result is Kapilla, Goddess of Orchards and Schools. The user combines these
two `Gods` to generate a `Pantheon`:

> Pantheon(Chetan, Kapilla)

The deities reproduce for several generations. The result in a `Pantheon` with a
few dozen `Gods` in it. One of these is Ajit, Demi-God of Talents, Crafts, and
Prancing.



# Models

### Attributes of a `God`

* **chromosomes**: Either `XX` or `XY`.
* **gender**: Either `male`, `female`, or `non_binary`.
* **genome**: A list of up to 46 words.
* **generation**: An integer set during a `pantheon.spawn()`.
* **divinity**: Either `god`, `demi_god`, or `human`.
* **name**: A string pulled at random from a list of `female_names`, `male_names`, or `nb_names`.
* **epithet**: A string that combines a title (God, Goddess, Divine Being, ...) with between 1 and 4 domains. A domain is a word randomly selected from the `God's` genome. Example: Goddess of hunting and war.
* **parents**: The `Gods` whose egg and sperm combined to create this `God`.

### Attributes of a `Pantheon`

* **gods**: A dictionary mapping names to `Gods`.

# Reproduction

### Spawning [Gods](https://github.com/carawarner/pantheon/blob/master/scripts/gods.py)
======================================================================================
How `Gods <https://github.com/carawarner/pantheon/blob/master/scripts/gods.py>`_ Spawn
======================================================================================

Given two `Gods`, one `XX` **egg donor** and one `XY` **sperm donor**...

1. Select a random word from the `God.genome` of the **egg donor**.
1. Use spaCy to pull 23 related words from the **gene pool**. This is the **egg**.
1. Select a random word from the `God.genome` of the **sperm donor**.
1. Use spaCy to pull 23 related words from the **gene pool**. This is the **sperm**.
1. Add the **egg** and **sperm** together. This list of 46 words is the *genome* for the new `God`.

_Note: because a `God's` genome is populated with words **related** to seeds from its parents' genomes, a `God` feels **genetically related** to its parents. But, because the seeds are selected at **random** from the parents' genomes, there's room for **genetic drift**._

### Spawning [Pantheons](https://github.com/carawarner/pantheon/blob/master/scripts/pantheons.py)
#. Select a random word from the `God.genome` of the **egg donor**.
#. Use spaCy to pull 23 related words from the **gene pool**. This is the **egg**.
#. Select a random word from the `God.genome` of the **sperm donor**.
#. Use spaCy to pull 23 related words from the **gene pool**. This is the **sperm**.
#. Add the **egg** and **sperm** together. This list of 46 words is the *genome* for the new `God`.

Given two `Gods`, one `XX` **egg donor** and one `XY` **sperm donor**, and a number of generations **N**...
*Note:* because a `God's` genome is populated with words related to seeds from its
parents' genomes, a `God` feels genetically related to its parents. But, because the
seeds are selected at random from the parents' genomes, there's room for genetic drift.

1. Declare a list of **egg donors** and a list of **sperm donors**.
1. Iterate **N** times, once for each generation...
1. At the start of each generation breed the **egg donors**.
1. At the end of each generation, add mature offspring to the breeding pool.
1. At the end of each generation, remove elder `Gods` from the breeding pool.

================================================================================================
How `Pantheons <https://github.com/carawarner/pantheon/blob/master/scripts/pantheons.py>`_ Spawn
================================================================================================

# Code Imitating Nature
Given two `Gods`, one `XX` **egg donor** and one `XY` **sperm donor**, and a number
of generations **N**...

The model blends randomness and probability to echo the beauty of nature.

**[Gender](https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L26-L35)**: There's a 7% chance a `God` will be transgendered and a 3% chance a `God` will be non-gendered or gender-queer. For this reason the model refers to 'egg donors' and 'sperm donors' not 'mothers' and 'fathers'. Two male `Gods` can procreate, as can two female `Gods`, or a gender-queer `God` and another `God`, as long as one parent is `XX` and one is `XY`.
#. Declare a list of **egg donors** and a list of **sperm donors**.
#. Iterate **N** times, once for each generation...
#. At the start of each generation breed the **egg donors**.
#. At the end of each generation, add mature offspring to the breeding pool.
#. At the end of each generation, remove elder `Gods` from the breeding pool.

**[Sex](https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L57)**: When a new `God` spawns, its sex chromosomes are chosen at random. It's possible for several `Gods` in a row to be `XX` or `XY`. An unexpected consequence of this: some Pantheons grow much faster than others. The rate of growth is determined by the number of `XX` gods born in each generation.

**[Mutation](https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L170-L172)**: The related words that spaCy finds in a list of plural nouns often feel "more related" than the ones it finds in a list of gerunds. This is just something I observed. 80% of the time this model pulls gametes from `primary_tokens`, which is a list of NNS; the other 20% of the time it pulls gametes from `secondary_tokens`, which is a list of VBG. The result is some children look a lot like their parents and some look very different; there's variety in how far the apple falls from the tree.
=============
More Features
=============

**[Power Level](https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L12-L24)**: Many traditions describe old gods as more powerful than young gods. When two `Gods` procreate there's a 30% chance their offspring will be a 'demi-god' rather than a full blown god. That chance jumps to 50% when a 'god' and 'demi-god' procreate, and when two 'demi-gods' procreate there's a 25% chance their offspring will be a lowly human.

**[Twinning](https://github.com/carawarner/pantheon/blob/master/scripts/pantheons.py#L65)**: 20% of the time coupling produces twins; the other 80% of the time it produces a single child.
The model blends randomness and probability to echo the beauty of nature.

**[Epithets](https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L149)**: Most gods (55%) represent 3 domains: God of X, Y, and Z. Slightly fewer gods (35%) represent two domains: God of X and Y. The remaining gods represent 1 or 4 domains.
`Gender <https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L26-L35>`_
**************************************************************************************
There's a 7% chance a `God` will be transgendered and a 3% chance a `God` will be non-
gendered or gender-queer. For this reason the model refers to 'egg donors' and 'sperm
donors' not 'mothers' and 'fathers'. Two male `Gods` can procreate, as can two female
`Gods`, or a gender-queer `God` and another `God`, as long as one parent is `XX` and
one is `XY`.

`Sex <https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L57>`_
*******************************************************************************
When a new `God` spawns, its sex chromosomes are chosen at random. It's possible for
several `Gods` in a row to be `XX` or `XY`. An unexpected consequence of this: some
Pantheons grow much faster than others. The rate of growth is determined by the number
of `XX` gods born in each generation.

`Mutation <https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L170-L172>`_
******************************************************************************************
The related words that spaCy finds in a list of plural nouns often feel "more related"
than the ones it finds in a list of gerunds. This is just something I observed. 80% of
the time this model pulls gametes from `primary_tokens`, which is a list of NNS; the
other 20% of the time it pulls gametes from `secondary_tokens`, which is a list of VBG.
The result is some children look a lot like their parents and some look very different;
there's variety in how far the apple falls from the tree.

`Power Level <https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L12-L25>`_
*******************************************************************************************
Many traditions describe old gods as more powerful than young gods. When two `Gods` procreate
there's a 30% chance their offspring will be a 'demi-god' rather than a full blown god. That
chance jumps to 50% when a 'god' and 'demi-god' procreate, and when two 'demi-gods' procreate
there's a 25% chance their offspring will be a lowly human.

`Twinning <https://github.com/carawarner/pantheon/blob/master/scripts/pantheons.py#L65>`_
*****************************************************************************************

20% of the time coupling produces twins; the other 80% of the time it produces a single child.

`Epithets <https://github.com/carawarner/pantheon/blob/master/scripts/gods.py#L149>`_
*************************************************************************************
Most gods (55%) represent 3 domains: God of X, Y, and Z. Slightly fewer gods (35%) represent
two domains: God of X and Y. The remaining gods represent 1 or 4 domains.
2 changes: 1 addition & 1 deletion setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
# $ pip install pantheon-generator
name='pantheon-generator', # Required

version='1.0.1', # Required
version='1.0.3', # Required

# This is a one-line description or tagline of what your project does. This
# corresponds to the "Summary" metadata field:
Expand Down

0 comments on commit 5918e0a

Please sign in to comment.