Merge pull request #121 from sfleischman105/Beta-Branch

Pleco Compilation on Stable, Optimizations, Doc Improvements

.travis.yml

@@ -5,7 +5,6 @@ rust:
 
 
 cache:
-
   - cargo
   - apt
 #  cache:
@@ -17,7 +16,7 @@ sudo: required
 env:
   global:
     - RUST_BACKTRACE=FULL
-    - RUSTFLAGS="-Ctarget-cpu=native -Zmutable-noalias"
+    - RUSTFLAGS="-Ctarget-cpu=native"
     - RUST_MIN_STACK=8000000
 #    - RUST_TEST_THREADS=1
 
@@ -34,11 +33,18 @@ env:
 #      - kalakris-cmake
 
 
+before_script:
+  - rustup install stable-x86_64-unknown-linux-gnu
+
 os:
   - linux
 
 script:
   - cargo build --verbose
+  - echo " ------ TESTING STABLE BRANCH ------- "
+  - cargo +stable test --package pleco
+  - cargo +stable bench --package pleco
+  - echo " ------ TESTING NIGHTLY BRANCH ------- "
   - cargo test --verbose
   - cargo bench
 #  - cd pleco/ && cargo bench

pleco/Cargo.toml

@@ -11,7 +11,7 @@ license = "MIT"
 categories = ["games","game-engines"]
 repository = "https://github.com/sfleischman105/Pleco"
 autobenches = false
-
+#build = "build.rs"
 
 include = [
     "src/*",
@@ -27,7 +27,6 @@ coveralls = { repository = "sfleischman105/Pleco", branch = "master", service =
 
 [lib]
 name = "pleco"
-#bench = true
 path = "src/lib.rs"
 doctest = true
 
@@ -61,15 +60,15 @@ bitflags = "1.0.4"
 rand = "0.6.5"
 rayon = "1.0.3"
 num_cpus = "1.10.0"
-prefetch = "0.2.0"
 mucow = "0.1.0"
 lazy_static = "1.3.0"
 
 [features]
 default = []
+nightly = []
 
 [dev-dependencies]
-criterion = { version = '0.2.10', default-features = false, features=['real_blackbox'] }
+criterion = { version = '0.2.10', default-features = false}
 
 [[bench]]
 name = "bench_main"

pleco/README.md

@@ -35,7 +35,7 @@ Use
 -------
 
 To use Pleco inside your own Rust projects, [Pleco.rs is available as a library on crates.io](https://crates.io/crates/pleco). 
-`nightly` rust is required to use. 
+Pleco runs on all three distributions (`nightly`, `beta`, `stable`) of rust.
 
 ### Basic Usage
 
@@ -95,6 +95,17 @@ board.undo_move();
 assert_eq!(board.moves_played(),0);
 ```
 
+#### Features
+
+If on nightly rust, the feature `"nightly"` is available. This enables some nightly
+optimizations and speed improvements.
+
+Usage is as easy as updating your `cargo.toml` to include:
+
+```
+[dependencies]
+pleco = {version = "*", features = ["nightly"]}
+```
 
 Contributing
 -------

pleco/benches/perft_benches.rs

@@ -38,8 +38,8 @@ fn perft_all(c: &mut Criterion) {
 
 criterion_group!(name = perft_benches;
      config = Criterion::default()
-        .sample_size(8)
-        .warm_up_time(Duration::from_millis(10));
+        .sample_size(12)
+        .warm_up_time(Duration::from_millis(20));
     targets = perft_all
 );
 

pleco/src/board/board_state.rs

@@ -20,7 +20,6 @@ use core::bitboard::BitBoard;
 use core::masks::*;
 use core::score::{Value,Score};
 
-//use std::sync::Arc;
 use tools::pleco_arc::Arc;
 use helper::prelude::*;
 
@@ -156,7 +155,7 @@ impl BoardState {
     ///
     /// Specifically, sets Blockers, Pinners, and Check Squares for each piece.
     ///
-    /// The `checkers_bb` must beset before this methof can be used.
+    /// The `checkers_bb` must beset before this method can be used.
     pub(crate) fn set_check_info(&mut self, board: &Board) {
         let mut white_pinners: BitBoard = BitBoard(0);
 

pleco/src/board/mod.rs

@@ -756,11 +756,10 @@ impl Board {
         }
         self.state = next_arc_state.shareable();
 
-        if cfg!(debug_assertions) {
-            self.is_okay().unwrap();
-        } else {
-            assert!(self.is_ok_quick());
-        }
+        #[cfg(debug_assertions)]
+        self.is_okay().unwrap();
+        #[cfg(not(debug_assertions))]
+        assert!(self.is_ok_quick());
     }
 
     /// Applies a UCI move to the board. If the move is a valid string representing a UCI move, then
@@ -855,11 +854,10 @@ impl Board {
         self.half_moves -= 1;
         self.depth -= 1;
 
-        if cfg!(debug_assertions) {
-            self.is_okay().unwrap();
-        } else {
-            assert!(self.is_ok_quick());
-        }
+        #[cfg(debug_assertions)]
+        self.is_okay().unwrap();
+        #[cfg(not(debug_assertions))]
+        assert!(self.is_ok_quick());
     }
 
     /// Apply a "Null Move" to the board, essentially swapping the current turn of
@@ -920,11 +918,10 @@ impl Board {
         }
         self.state = next_arc_state.shareable();
 
-        if cfg!(debug_assertions) {
-            self.is_okay().unwrap();
-        } else {
-            assert!(self.is_ok_quick());
-        }
+        #[cfg(debug_assertions)]
+        self.is_okay().unwrap();
+        #[cfg(not(debug_assertions))]
+        assert!(self.is_ok_quick());
     }
 
     /// Undo a "Null Move" to the Board, returning to the previous state.
@@ -1980,6 +1977,12 @@ impl Board {
 
     /// `see_ge` stands for Static Exchange Evaluation, Greater or Equal. This teats if the
     /// Static Exchange Evaluation of a move is greater than or equal to a value.
+    ///
+    /// This is a recursive algorithm that works by checking the destination square of
+    /// the given move, and attempting to repeatedly capture that spot for both players.
+    ///
+    /// If the move is invalid for the current board, `false` will be returned regardless
+    /// of the threshold.
     pub fn see_ge(&self, mov: BitMove, threshold: i32) -> bool {
         if mov.move_type() != MoveType::Normal {
             return 0 >= threshold;

pleco/src/board/piece_locations.rs

@@ -46,7 +46,7 @@ impl PieceLocations {
     ///
     /// # Panics
     ///
-    /// Panics if Square is of index higher than 63.
+    /// Panics if Square is of index higher than 63 or the piece is `PieceType::{None || All}`
     #[inline]
     pub fn place(&mut self, square: SQ, player: Player, piece: PieceType) {
         debug_assert!(square.is_okay());

pleco/src/core/bitboard.rs

@@ -163,14 +163,22 @@ impl BitBoard {
 
     /// Returns the index (as a square) of the least significant bit and removes
     /// that bit from the `BitBoard`.
+    ///
+    /// # Safety
+    ///
+    /// Panics if the `BitBoard` is empty. See [`BitBoard::pop_some_lsb`] for a
+    /// non-panicking version of the method.
+    ///
+    /// [`BitBoard::pop_some_lsb`]: struct.BitBoard.html#method.pop_some_lsb
     #[inline(always)]
     pub fn pop_lsb(&mut self) -> SQ {
         let sq = self.bit_scan_forward();
         *self &= *self - 1;
         sq
     }
 
-    /// Returns the least significant bit of a `BitBoard`, if it has any.
+    /// Returns the least significant bit of a `BitBoard`, if it has any. If there is a bit to
+    /// return, it removes that bit from itself.
     #[inline(always)]
     pub fn pop_some_lsb(&mut self) -> Option<SQ> {
         if self.is_empty() {
@@ -182,13 +190,23 @@ impl BitBoard {
 
     /// Returns the index (as a square) and bit of the least significant bit and removes
     /// that bit from the `BitBoard`.
+    ///
+    /// # Safety
+    ///
+    /// Panics if the `BitBoard` is empty. See [`BitBoard::pop_some_lsb_and_bit`] for a
+    /// non-panicking version of the method.
+    ///
+    /// [`BitBoard::pop_some_lsb_and_bit`]: struct.BitBoard.html#method.pop_some_lsb_and_bit
     #[inline(always)]
     pub fn pop_lsb_and_bit(&mut self) -> (SQ, BitBoard) {
         let sq: SQ = self.bit_scan_forward();
         *self &= *self - 1;
         (sq, sq.to_bb())
     }
 
+    /// Returns the index (as a square) and bit of the least significant bit and removes
+    /// that bit from the `BitBoard`. If there are no bits left (the board is empty), returns
+    /// `None`.
     #[inline(always)]
     pub fn pop_some_lsb_and_bit(&mut self) ->  Option<(SQ, BitBoard)> {
         if self.is_empty() {
@@ -202,7 +220,7 @@ impl BitBoard {
     ///
     /// # Safety
     ///
-    /// panics if the `BitBoard` is empty.
+    /// Panics if the `BitBoard` is empty.
     #[inline]
     pub fn frontmost_sq(self, player: Player) -> SQ {
         match player {

pleco/src/core/masks.rs

@@ -243,6 +243,17 @@ pub static SQ_DISPLAY_ORDER: [u8; SQ_CNT] = [56, 57, 58, 59, 60, 61, 62, 63,
     8,  9,  10, 11, 12, 13, 14, 15,
     0,  1,   2,  3,  4,  5,  6,  7];
 
+/// Array mapping a square index to a string representation.
+///
+/// # Examples
+///
+/// ```
+/// use pleco::core::masks::SQ_DISPLAY;
+///
+/// assert_eq!(SQ_DISPLAY[0], "a1");
+/// assert_eq!(SQ_DISPLAY[1], "b1");
+/// assert_eq!(SQ_DISPLAY[8], "a2");
+/// ```
 pub static SQ_DISPLAY: [&str; SQ_CNT] = [
     "a1", "b1", "c1", "d1", "e1", "f1", "g1", "h1",
     "a2", "b2", "c2", "d2", "e2", "f2", "g2", "h2",
@@ -254,13 +265,34 @@ pub static SQ_DISPLAY: [&str; SQ_CNT] = [
     "a8", "b8", "c8", "d8", "e8", "f8", "g8", "h8"];
 
 /// Characters for each combination of player and piece.
+///
+/// White pieces are displayed as Uppercase letters, while black pieces are lowercase.
 pub static PIECE_DISPLAYS: [[char; PIECE_TYPE_CNT]; PLAYER_CNT] = [
     ['_', 'P', 'N', 'B', 'R', 'Q', 'K', '*'],
     ['_', 'p', 'n', 'b', 'r', 'q', 'k', '*'],
 ];
 
 /// Characters for each file, index from file A to file H.
+/// # Examples
+///
+/// ```
+/// use pleco::core::masks::FILE_DISPLAYS;
+///
+/// assert_eq!(FILE_DISPLAYS[0], 'a');
+/// assert_eq!(FILE_DISPLAYS[1], 'b');
+/// assert_eq!(FILE_DISPLAYS[7], 'h');
+/// ```
 pub static FILE_DISPLAYS: [char; FILE_CNT] = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
 
 /// Characters for each rank, index from rank 1 to rank 8.
+///
+/// # Examples
+///
+/// ```
+/// use pleco::core::masks::RANK_DISPLAYS;
+///
+/// assert_eq!(RANK_DISPLAYS[0], '1');
+/// assert_eq!(RANK_DISPLAYS[1], '2');
+/// assert_eq!(RANK_DISPLAYS[7], '8');
+/// ```
 pub static RANK_DISPLAYS: [char; FILE_CNT] = ['1', '2', '3', '4', '5', '6', '7', '8'];

pleco/src/core/mono_traits.rs

@@ -4,7 +4,7 @@
 //! This modules only use is to allow for compile-time mono-morphization of
 //! functions / methods, where each method created can be optimized further.
 //!
-//! We are awaiting the stabilization of `const fn` to remove these traits.
+//! We are awaiting the stabilization of `const fn` and constant generics to remove these traits.
 
 use super::{Player, PieceType, GenTypes};
 use super::sq::SQ;