Metadata-Version: 2.0
Name: pyfastnoisesimd
Version: 0.2.1
Summary: Python Fast Noise with SIMD
Home-page: http://github.com/robbmcleod/pyfastnoisesimd
Author: Robert A. McLeod
Author-email: robbmcleod@gmail.com
License: https://opensource.org/licenses/BSD-3-Clause
Description-Content-Type: UNKNOWN
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix

PyFastNoiseSIMD
===============

PyFastNoiseSIMD is a wrapper around Jordan Peck's synthetic noise library 
https://github.com/Auburns/FastNoise-SIMD which has been 
accelerated with SIMD instruction sets. It may be installed via pip:

    pip install pyfastnoisesimd

Source and Windows Python 3.6 wheels are provided.

Here is a simple example to generate Perlin-style noise on a 3D rectilinear 
grid::

    import pyfastnoisesimd as fns
    import numpy as np
    shape = [512,512,512]
    seed = np.random.randint(2**31)
    N_threads = 4

    perlin = fns.Noise(seed=seed, numWorkers=N_threads)
    perlin.frequency = 0.02
    perlin.noiseType = fns.NoiseType.Perlin
    perlin.fractal.octaves = 4
    perlin.fractal.lacunarity = 2.1
    perlin.fractal.gain = 0.45
    perlin.perturb.perturbType = fns.PerturbType.NoPertrub
    result = perlin.genAsGrid(shape)

where ``result`` is a 3D ``numpy.ndarray`` of dtype ``'float32'``. Alternatively, 
the user can provide coordinates, which is helpful for tasks such as 
custom bump-mapping a tessellated surface, via ``Noise.getFromCoords(coords)``. 

More extensive examples are found in the ``examples`` folder on the Github repository.

Parallelism is further enhanced by the use of ``concurrent.futures`` to multi-thread
the generation of noise for large arrays. Thread scaling is generally in the 
range of 50-90 %, depending largely on the vectorized instruction set used. 
The number of threads, defaults to the number of virtual cores on the system.


Benchmarks
---------- 

The first test is used the default mode, a cubic grid, ``Noise.genAsGrid()``.

**Array shape**: [8,1024,1024]
**CPU**: Intel i7-7820X Skylake-X (8 cores, 3.6 GHz), Windows 7
**SIMD level supported**: AVX2 & FMA3

Single-threaded mode
~~~~~~~~~~~~~~~~~~~
Computed 8388608 voxels cellular noise in 0.298 s
    35.5 ns/voxel
Computed 8388608 voxels Perlin noise in 0.054 s
    6.4 ns/voxel


Multi-threaded (8 threads) mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Computed 8388608 voxels cellular noise in 0.044 s
    5.2 ns/voxel
    685.0 % thread scaling
Computed 8388608 voxels Perlin noise in 0.013 s
    1.5 ns/voxel
    431.3 % thread scaling


The alternative mode is ``Noise.getAsCoords()`` where the user provides the 
coordinates in Cartesian-space:

Single-threaded mode
~~~~~~~~~~~~~~~~~~~
* Generated noise from 2666000 coordinates with 1 workers in 1.935e-02 s (7.3 ns/pixel)

Multi-threaded (8 threads) mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Not implemented at present


Release Notes
-------------

**0.2.1**

* Drop explicit Python 3.4 support as we cannot test it for Windows on MSVC2010
  and in any case it wouldn't have AVX2 instruction support.
* Start tagging, see `RELEASING_GUIDE.txt` for notes.

**0.2.0**

* Added the capability to provide coordinates 
* Added ``examples/projection.py`` to demonstrate noise generation by supplied 
  coordinates as applied to a Gall-Peters cylindrical projection of a sphere 
  (i.e. a world map).
* Added ``Noise`` object-oriented interface.  ``Noise`` uses Python properties to 
  expose the ``Set/Get`` functions in ``FastNoiseSIMD``.
* Added ``unittest`` support.
* Deprecated 'kitchen sink' ``pyfastnoisesimd.generate()`` function.
* Changed README from markdown to rich-structured text.
* Fixed a bug in the deprecated ``pyfastnoisesimd.generate()`` that always set 
  the seed to 42.
* Fixed spelling errors: ``axisScales`` -> ``axesScales``, ``indicies`` -> ``indices``

**0.1.5**

* Using all lower-case directories for *nix.

**0.1.4**

* Fixed bug on multithreading; current approach splits arrays up to min(threads, array.shape[0])

**0.1.2**

* Added MANIFEST.in file for source distribution on PyPI


FastNoiseSIMD library
---------------------

If you want a more direct interface with the underlying library you may use the 
``pyfastsimd._ext`` module, which is a function-for-function mapping to the C++ 
code.

FastNoiseSIMD is implemented by Jordan Peck, and may be found at: 

https://github.com/Auburns/FastNoiseSIMD

It aims to provide faster performance through the use of intrinsic(SIMD) CPU 
functions. Vectorisation of the code allows noise functions to process data in 
sets of 4/8/16 increasing performance by 700% in some cases (Simplex).

See the Wiki for usage information on the noise types:

https://github.com/Auburns/FastNoiseSIMD/wiki

Download links for a GUI-based reference noise generator may be found at:

https://github.com/Auburns/FastNoiseSIMD/releases



