README

-------------------------------------------------------------------------------
OVERVIEW
-------------------------------------------------------------------------------

YAFU (with assistance from other free software) uses the most powerful modern
algorithms (and implementations of them) to factor input integers in a 
completely automated way.  The automation within YAFU is state-of-the-art, 
combining factorization algorithms in an intelligent and adaptive methodology 
that minimizes the time to find the factors of arbitrary input integers.  

YAFU has been referenced several times in the academic literature.  If you have 
academic work that requires integer factorization, YAFU might be able to help.  

YAFU is most optimized for general inputs up to 160 digits in size, although 
there is support for inputs much larger than that, if they have a special 
form.  There are also specialized functions for handling lists of inputs and 
ranges of contiguous smaller inputs.

YAFU is primarily a command-line driven tool.  You provide the number to factor
and, via screen output and log files, YAFU will provide you the factors.  
But that's not all!  You also get an interactive environment similar to MATLAB
or PARI/GP, where you can type commands and store results.  The functionality
of this interface is limited, but perhaps useful, and I have plans to make it
better.  YAFU also provides a vast amount of flexibility, through many many
options and a very capable expression interpreter.  If you know what you are
doing, or if you read the documentation enough, you can customize the operation
of YAFU a great deal.  You should have received a copy of docfile.txt, which
explains in some detail all of the available functions, how to use them,
and how to influence their behavior.  A community of factorization enthusiasts 
can be found at mersenneforum.org, many of whom are willing and able to 
answer questions.

-------------------------------------------------------------------------------
INSTALLATION
-------------------------------------------------------------------------------

No installation necessary, just put the binary in whatever location you like 
and run it.  Files that YAFU generates are placed alonside the binary, and 
directories/files that YAFU needs are with respect to the binary location 
(such as the ggnfs sievers, see below)

Please note that the windows executable provided here contains the most
basic implementation of many of the factorization algorithms, in order to 
run on the largest number of processors.  If you want to enhance yafu's 
performance for your processor, you will have to build your own copy from 
source.  This can be done with free tools for Windows or Linux operating 
systems.  See below for build information.  More detailed guides can be 
found online at mersenneforum.org.


Support and an active user community can be found here:
https://www.mersenneforum.org/node/58


-------------------------------------------------------------------------------
BUILD INFORMATION
-------------------------------------------------------------------------------

Pre-compiled binaries are provided for windows.  However, anyone 
is welcome to compile from source for your own system.  If you can make a 
binary which beats the performance of one of the pre-compiled versions for a 
particular architecture, I'd love to hear about it!

Linux 64 bit OS (including Windows Subsystem for Linux, WSL)
=============
make yafu [USE_SSE41=1] [USE_AVX2=1] [USE_BMI2=1] [SKYLAKEX=1] [ICELAKE=1] [VBITS=64/128/256/512]

I've built and tested with gcc, icc, and a couple versions of clang

As of version 3.0 YAFU now only requires GMP and GMP-ECM as dependencies.  
Ytools, ysieve, and msieve are now included into the project locally and built 
as needed during make.
gmp (https://gmplib.org/)
gmp-ecm (http://ecm.gforge.inria.fr/)

Here are some terse notes on how to build these dependencies prior to yafu.  Specific
arguments to "make" in some cases could change depending on your system.

GMP
./configure --prefix="/path/to/a/gmp/install/location/"
make
make install

GMP-ECM
autoreconf -i
./configure --prefix="/path/to/a/ecm/install/location/" --with-gmp="/path/to/a/gmp/install/location/"
make
make install

YAFU
edit makefile to add the following to CFLAGS:
-I/path/to/a/gmp/install/location/include/ -L/path/to/a/gmp/install/location/lib
-I/path/to/a/ecm/install/location/include/ -L/path/to/a/ecm/install/location/lib
make yafu [USE_SSE41=1] [USE_AVX2=1] [USE_BMI2=1] [SKYLAKEX=1] [ICELAKE=1] [VBITS=64/128/256/512]

Some support can be had here:
http://www.mersenneforum.org/forumdisplay.php?f=96

If your computer supports them, yafu can make use of several modern instruction
set extensions, including SSE41, AVX2, and AVX512 (various extensions).
SKYLAKEX will add support for AVX512F and AVX512BW.
ICELAKE will add support for AVX512F, AVX512BW, and AVX512IFMA.
Primarily these are used in SIQS.  If you have AVX512 on your cpu, yafu will
also use AVX-ECM as the default ECM implementation.  For a standalone 
version of AVX-ECM, please refer to:
https://github.com/bbuhrow/avx-ecm


WINDOWS MS Visual Studio
=============

Build files are available for Microsoft visual studio, available for free
online.

You will need several other visual studio projects installed and built 
before attempting to build yafu.

As of yafu version 3.0 (Jan 2025) I get these from these locations:
mpir: https://github.com/BrianGladman/mpir
ecm: https://gitlab.inria.fr/zimmerma/ecm/-/releases
or https://github.com/sethtroisi/gmp-ecm
pthreads: https://github.com/BrianGladman/pthreads

These all come with MSVC build files that should work.

To configure yafu once its dependencies are built, use the 
libs_and_extensions.props file in the build.vc22 directory.
Here you can supply directories to the builds, relative to yafu's
project directories (e.g., build.vc22\ecm)

A little farther down in the libs_and_extensions.props file, edit
the PreprocessorDefinitions line with any instruction set extensions you
want to enable for yafu's build.

I have also had success installing and using the free Intel compiler inside
visual studio 2022.

MINGW-64
=============
YAFU might build in mingw-64 environment.  I haven't tried in a long time;
good luck.  If you get this to work, please let me know.

OTHER
=============
If you build yafu on other platforms or using other IDE's or
compilers, please let me know about it.


-------------------------------------------------------------------------------
HELP INFORMATION
-------------------------------------------------------------------------------

Detailed documentation is available in docfile.txt, which can be viewed during 
an interactive YAFU session by typing 'help'.  The default yafu.ini also 
contains descriptions of available options.

If you want to see the docfile from within the program, it needs to be in the 
same directory as the executable.

Check back at https://github.com/bbuhrow/yafu for updates.

---------------------------------------------------------------
MISC INFORMATION
---------------------------------------------------------------
Here's a fun test case for factor(), which uses many of the 
algorithms in yafu
factor(2056802480868100646375721251575555494408897387375737955882170045672576386016591560879707933101909539325829251496440620798637813)

neat example for ecm:
140870298550359924914704160737419905257747544866892632000062896476968602578482966342704