oscarsaleta / P4

P4 (Polynomial Planar Phase Portraits) software for phase portrait computation and representation in the plane or other projections such as the Poincaré Sphere.

P4 (Polynomial Planar Phase Portraits) version 8.0.1 - beta

Description

P4 is a software that is able to draw the planar phase portrait for any polynomial differential system on the Poincaré or Poincaré-Lyapunov compactified planes.

Check the installation instructions for Linux, Windows and macOS, and also check out the FAQ or open an issue if you have any problems with the software.

Linux

Installation

Check release page to see more detailed instructions and download links.

0. Check dependencies, every item must be satisfied
1. Clone the repository: git clone https://github.com/oscarsaleta/P4.git P4-git && cd P4-git,
2. Execute the installation script ./compile_install_p4 and follow the instructions,
3. Done!

Dependencies

Maple must be installed in the computer in order to use P4.

• Make sure you can execute Maple by typing maple in the command line. This means that the directory where Maple is installed must be in the path.
  • Modify your shell configuration file (.bashrc, .zshrc, etc): export PATH="/path/to/Maple/bin:$PATH", where /path/to/Maple/ must be replaced by the path to the Maple installation in your system.
  • Source the configuration file or open a new terminal to apply the changes.

• Installation with compile_install_p4 or compilation from source using qmake:
  • Git: must have to work with git projects:
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install git
    • Fedora-based (Fedora/Kokora/Arquetype): sudo dnf install git
    • Arch-based (Archlinux/Antergos): sudo pacman -S git
    • (See the git ArchWiki page for more information and configuration instructions).
  • Qt modules QtCore, QtGui, QtWidgets, QtPrintSupport (minimum required version 5.2.1, recommended version >= 5.5.0):
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install qt5-default
    • Fedora-based (Fedora/Kokora/Arquetype): sudo dnf install qt5*-devel --allowerasing
    • Arch-based (Archlinux/Antergos): sudo pacman -S qt5-base
    • Any Linux distribution (recommended for getting the latest version): can be downloaded from the Qt website
  • qmake (version 3.0 recommended):
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install qt5-qmake
    • Other distros: already installed if you followed the install instructions for Qt 5.
  • C++ compiler: g++ (version >= 4.9 recommended, must support the C++11 standard):
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install gcc g++
    • Fedora-based (Fedora/Kokora/Arquetype): sudo dnf group install 'Development Tools'
    • Arch-based (Archlinux/Antergos): sudo pacman -S gcc
  • pkg-config (0.28 or greater):
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install pkg-config
    • Fedora-based (Fedora/Kokora/Arquetype): sudo dnf install pkgconfig
    • Arch-based (Archlinux/Antergos): sudo pacman -S pkg-config
  • mpfr library (version >= 3.1.2):
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install libmpfr-dev
    • Fedora-based (Fedora/Kokora/Arquetype): sudo dnf install mpfr-devel
    • Arch-based (Archlinux/Angergos): sudo pacman -S gmp mpfr
• Compilation from source using Qt Creator:
  • Dependencies itemized above,
  • Qt Creator IDE:
    • Debian-based (Debian/Ubuntu/Mint): sudo apt-get install qtcreator
    • Fedora-based (Fedora/Kokora/Arquetype): sudo dnf install qt-creator
    • Arch-based (Archlinux/Antergos): sudo pacman -S qtcreator

Windows

Installation

Check release page to see more detailed instructions and download links.

1. Download P4_windows-setup_*.exe from here,
2. Execute installer and follow the instructions,
3. Done!

Dependencies

Maple must be installed in the computer in order to use P4.

• Installation using P4setup.exe:
  • Dependencies are taken care of.
• Compilation from source using Qt Creator:
  • Qt modules QtCore, QtGui, QtWidgets, QtPrintSupport (minimum required version 5.2.1, could work for 4.6.0 but it has not been tested).
    • Download from Qt website,
  • C++ compiler: Microsoft Visual C++ Compiler (tested with versions 14.0 and 15.0).
    • Download from Visual Studio Community.

macOS

Installation

Check release page to see more detailed instructions and download links.

0. Check dependencies, every item must be satisfied. The installation script will try to solve some of the dependencies but it is much easier if you manually install them following the instructions.
1. Clone the repository git clone https://github.com/oscarsaleta/P4.git P4-git && cd P4-git,
2. Execute the installation script ./compile_install_p4 and follow the instructions,
3. Done!

Dependencies

Maple must be installed in the computer in order to use P4.

• Make sure you can execute Maple by typing maple in Terminal:
  • Edit your shell configuration file (.bashrc, .zshrc, etc) with the following line: export PATH="/Library/Frameworks/Maple.framework/Versions/XXX/bin:$PATH", where XXX should be replaced by your installed Maple version.
  • Restart the Terminal for the changes to be effective.

• Installation of pre-compiled binaries:
  • Homebrew: package manager for macOS that will help us install Qt and MPFR (see Homebrew website)
    • Run in terminal: /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Qt and qmake: installed using Homebrew
    • Run in terminal brew install qt
    • Follow the instructions (IMPORTANT: modify the PATH as the installer suggests so the system will be able to find the libraries): echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bashrc
• Installation with compile_install_p4:
  • Xcode: macOS suite for software development. Install from the App Store, then open it and accept the Terms of Use.
  • Comand line developer tools: this adds necessary programs such as git and clang to the system.
    • To install, run xcode-select --install in Terminal
  • Homebrew: package manager for macOS that will help us install Qt and MPFR (see Homebrew website)
    • Run in terminal: /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Qt and qmake: installed using Homebrew
    • Run in terminal brew install qt
    • Follow the instructions (IMPORTANT: modify the PATH as the installer suggests so the system will be able to find the libraries): echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bashrc
  • MPFR library: installed using Homebrew
    • Run in terminal brew install mpfr
  • You will need to open a new terminal if you updated the PATH for the changes to take effect

Manually build P4 from source in UNIX systems

Automatic build and install for Linux using compile_install_p4

This is the easiest way in Linux and macOS to get a working P4 application.

• Clone this repository: git clone https://github.com/oscarsaleta/P4.git.
• Change directory into the repository folder: cd P4.
  • If you want the newest unstable version of P4 (which is not as tested as the stable release), checkout the release candidate branch: git checkout release_candidate.
• Execute the script and follow the instructions: ./compile_install_p4. This will check for dependencies, compile, and install P4 in your computer (if requirements are met).

Build using qmake

Qt's qmake makes it easy to compile the whole project with two commands.

• From the root of the project, run qmake -r P4.pro in order to generate the Makefiles.
• From this same directory, run make to compile p4, lyapunov and separatrice.
  • The output of the compilation will be found in a new directory named build.
  • The make command also compiles mplstrip, which is a C++ program used to generate Maple scripts inside src-mpl.
• If your Maple version is NOT 2015: go into src-mpl and execute:
  • make -f MakeTexMaple clean
  • make -f MakeTexMaple all This will generate p4gcf.m and p4.m, two Maple scripts needed by P4.
• From the root directory of the project, run make install to generate a p4 folder with the layout explained here. This directory can be placed anywhere in the system and P4 can be executed using /path/to/p4/bin/p4.
• It is advisable that you set the environment variable P4_DIR=/path/to/p4 to the correct path of the P4 directory in your shell configuration script (.bashrc, .zshrc, etc.).

Build using Qt Creator

Check here for instructions on how to build this project using Qt Creator.

Binary tree

Check here for instructions of how to create a correct file tree for P4 to work after each of its parts has been compiled.

Files

• binaries: some development scripts that help creating binaries for Linux and Windows (this directory doesn't actually contain any binaries, you can find those here).
• help: Help files in .html format and supporting images.
• mpir: (relevant to Windows only) copy of MPIR repository, a fork of GMP (GNU Multiprecision library), for multiprecision integer computations.
• mpfr: (relevant to Windows only) copy of MPFR repository, the GNU MPFR library, for multiprecision floating point computations.
• QtCreator: files and projects for building P4 using Qt Creator.
• src-gui:
  • lyapunov: C++ code for numerical computation of Lyapunov constants
  • lyapunov_mpf: C++ code for numerical computation of Lyapunov constants (multiprecision version)
  • p4: C++/Qt source code for the GUI of P4,
  • separatrice: C++ code for numerical computation of separatrices
• src-mpl: Maple scripts that drive the computations of P4 (finding singular points, algebraic computation of Lyapunov constants, blow-ups, etc.).

FAQ

• I installed P4 using precompiled binaries, but the program doesn't work.
  • Precompiled binaries often work only in systems equivalent to those in which the compilation was performed (due to missing libraries or mismatching software versions). This is why in Linux and macOS it is recommended to use the compile_install_p4, which compiles P4 to adapt to the system characteristics.
• I installed P4 and it executes, but when I press Evaluate the output window shows "External Command: /some/maple/command untitled.txt" and does nothing.
  • This means that /some/maple/command is not a recognised command in your system.
    • Linux and macOS: Check that you have Maple installed and that maple is a valid command in the terminal (see Linux or macOS instructions).
    • Linux, Windows and macOS: go to About P4... > Main Settings and check that the Maple Executable field points to the right Maple installation directory or has the correct maple command.
• I installed P4 and it executes, but when I press Evaluate the output says "Error, could not open `/path/to/p4/bin/p4.m` for reading" (or similar).
  • Check that /path/to/p4 in the Maple output is the correct path for your P4 installation.
    • If the path is correct: check that the files p4.m and p4gcf.m exist in the P4 installation directory. If they don't, then you need to reinstall P4 because something went wrong and the installation did not complete properly.
    • If the path is wrong: check that you defined correctly the P4_DIR environment variable in .bashrc (or .zhsrc, or any other shell configuration file you use). Also, within P4, go to About P4... > Main Settings and check that the Base installation Path and the Sumtable Path fields point correctly to your P4 installation directory.
• I installed P4 and it executes, but when I press Evaluate the output says "Error, at offset 17729 in /usr/local/p4/bin/p4.m, unexpected DAG type: 0,122,(z)" (or similar) and then does nothing.
  • This is a known bug that still has not been solved. We suspect it has to do with older Maple versions not being fully compatible with P4. P4 has been tested with Maple 17, 18 and 2015 (and recently 2017 thanks to a commited user), but older Maple versions could cause incompatibilities.
  • Our advice is to either acquire a newer Maple version, or use an older P4 version where this issue does not appear (as of now, the latest P4 version without this problem is v3.3.3).
• Where are my files and images saved?
  • It depends on the OS: for Linux and Mac, the files are stored in the current working directory of the Terminal that executed P4. For Windows, the files are all saved to C:\Users\currentUser\Documents\P4 or the equivalent Documents directory.
  • The name of the files depends on the name inputted in the field Name on top of the P4 application. Be careful, because if you use the same name for printing two different vector fields, the oldest will be replaced.

Contributors

• J.C. Artés (Universitat Autònoma de Barcelona)
• P. De Maesschalck (Hasselt University)
• F. Dumortier (Hasselt University)
• C. Herssens (Hasselt University)
• J. Llibre (Universitat Autònoma de Barcelona)
• O. Saleta (Universitat Autònoma de Barcelona)
• J. Torregrosa (Universitat Autònoma de Barcelona)