Skip to content
Merged
25 changes: 25 additions & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
ArmstrongJ
Benjamin Greiner
Cheng Soon
Clancy Rowley
Enrico Avventi
Gilles Plessis
JKP3nt
Jake Vanderplas
James Goppert
Jason K. Moore
Jerker Nordh
Johannes Scharlach
Joris Geysens
Lauren Padilla
Lucas Mehl
Marcus Liljedahl
René van Paassen
Richard Murray
Rory Yorke
Scott C. Livingston
Steve Brunton
arnold
clementm
eph
lytex
3 changes: 2 additions & 1 deletion COPYING
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
Copyright (c) 2002-2009 NICONET e.V.
Copyright 2010-2011 Enrico Avventi
Copyright (C) 2012-2020 Slycot team

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
Expand All @@ -13,4 +14,4 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
MA 02110-1301, USA.
MA 02110-1301, USA.
6 changes: 0 additions & 6 deletions CREDITS

This file was deleted.

4 changes: 2 additions & 2 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
include slycot/src/*.pyf
include COPYING
include CREDITS
include AUTHORS
include gpl-2.0.txt
include README.rst
include MANIFEST.in
Expand All @@ -13,4 +13,4 @@ include slycot/*.py
include slycot/version.py.in
include slycot/src/*.f
include slycot/tests/*.py
include runtests.py

136 changes: 88 additions & 48 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,16 @@ Slycot
.. image:: https://travis-ci.org/python-control/Slycot.svg?branch=master
:target: https://travis-ci.org/python-control/Slycot

.. image:: https://coveralls.io/repos/python-control/slycot/badge.png
:target: https://coveralls.io/r/python-control/slycot
.. image:: https://coveralls.io/repos/github/python-control/Slycot/badge.svg
:target: https://coveralls.io/github/python-control/Slycot

Python wrapper for selected SLICOT routines, notably including solvers for
Riccati, Lyapunov, and Sylvester equations.

Dependencies
------------

Slycot supports Python versions 2.7 and >=3.5.
Slycot supports Python versions 2.7, and 3.5 or later.

To run the compiled Slycot package, the following must be installed as
dependencies:
Expand All @@ -32,50 +32,40 @@ following dependencies:

- Python 2.7, 3.5+
- NumPy
- scikit-build >=0.8.1
- cmake
- scikit-build >= 0.10.0
- CMake
- C compiler (e.g. gcc, MS Visual C++)
- FORTRAN compiler (e.g. gfortran, ifort, flang)
- BLAS/LAPACK (e.g. OpenBLAS, ATLAS, MKL)

To run the Slycot unit tests and examples, you'll also need scipy and
pytest.

There are a variety of ways to install these dependencies on different
operating systems. See the individual packages' documentation for options.

Installing
-----------

In general Slycot requires non-trivial compilation to install on a given
system. The easiest way to get started using Slycot is by installing
pre-compiled binaries. The Slycot team provides pre-compiled binaries via the
conda package manager and conda forge package hosting channel for Linux, OSX,
and Windows.

Using conda
~~~~~~~~~~~

Install Miniconda or Anaconda and then Slycot can be installed via the conda
package manager from the conda-forge channel with the following command::

conda install -c conda-forge slycot
The easiest way to get started with Slycot is to install pre-compiled
binaries from conda-forge (see below); these are available for Linux,
OSX, and Windows.

Using pip
~~~~~~~~~
Compiling the Slycot source is unfortunately a bit tricky, especially
on Windows, but we give some pointers further below for doing this.

Slycot can also be installed via the pip package manager. Install pip as per
recommendations in pip's documentation. At a minimum, Python and pip must be
installed. If a pre-complied binary (i.e. "wheel") is available it will be
installed with no need for compilation. If not, pip will attempt to compile the
package from source and thus the compilation dependencies will be required
(scikit-build, gfortran, BLAS, etc.).
Using conda and conda-forge
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pip can then be used to install Slycot with the command::
First install Miniconda or Anaconda. Slycot can then be installed
from the conda-forge channel with the following command::

pip install slycot
conda install -c conda-forge slycot

From source
~~~~~~~~~~~
From source without conda (Linux, macOS, Windows)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unpack the course code to a directory of your choice,
Unpack the source code to a directory of your choice,
e.g. ``/path/to/slycot_src/``

If you need to specify a specific compiler, set the environment variable FC
Expand All @@ -87,35 +77,85 @@ before running the install::
# Windows:
set FC=D:\path\to\my\fortran.exe

To build and install execute::
To build and install, execute::

cd /path/to/slycot_src/
python setup.py install

You can also use conda to build and install Slycot from source::
From source using a conda recipe (Linux and macOS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

conda build conda-recipe
conda install --use-local slycot
You can also use conda to build and install Slycot from source, but
you'll have to choose the right recipe directory.

If you prefer to use the OpenBLAS library, a conda recipe is available in
``conda-recipe-openblas``.
On Linux you can choose between ``conda-recipe-openblas`` and
``conda-recipe-mkl``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that there seems to be relatively new way for users to switch between blas versions: https://conda-forge.org/docs/maintainer/knowledge_base.html#blas

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's only for users getting their packages from conda-forge not for using conda-build locally, though? So rather something for the conda-feedstock package than for the instructions here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but it begs the question for me why Slycot wants to try to provide conda build instructions for non-defaults/conda-forge dependencies. Building a compatible set of conda binaries locally has to pull dependencies from somewhere or you have to build the whole stack locally. Mixing the underlying blas/lapack/etc libs with those in conda-forge and defaults is likely asking for trouble.

What is the reason for having these conda build scripts in slycot at this point in time? Doesn't the setup.py that's now powered by scikit build let users do custom installations sufficiently?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Totally agree, that the current mixing is asking for trouble.

The linked article implies that it should not matter against which library the build is linked during compile time, because the implementations should be ABI compatible. Maybe we are overcomplicating things here and if we still want to provide a recipe just give a single default one?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why we maintain these conda-build recipes, especially given the existence of slycot-feedstock.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The recipes in the feedstock are normal conda recipes. I just tested on Ubuntu 20.04. I cloned the feedstock recipe, cd'd into the recipe directory, and did conda build -c conda-forge .. It built successfully and passed the tests. There are some parts of the recipe that are specific to conda forge, e.g. disabling the python 2.7 builds for windows, which a user would have to remove if they wanted to do that build.

OK, but at the top of the recipe is this:

{% set version = "0.3.5.0" %}
{% set sha256 = "cad98d5ea4f0a034cf398c39189f587620a0b03f1d4b71e77cd622a327f13adf" %}

package:
  name: slycot
  version: {{ version }}

source:
  url: https://pypi.io/packages/source/s/slycot/slycot-{{ version }}.tar.gz

which means 0."build 3.5 from PyPI", right? This is appropriate for the feedstock, but doesn't easily let one build other versions.

This is all OK, I just want to be sure I understand.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A user can change the version number and see if it builds, but if you want to make old builds you would likely need to checkout a prior commit in the feedstock recipe corresponding to a previous version. But, that said, keeping old builds working as time passes will get increasingly hard due to updates in conda, conda build, and any dependencies. You'd have to build with old versions of conda and put max versions on the dependencies, etc.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the question is more about building a more recent version from the git repository instead of the released 0.3.5 (or hopefully soon 0.4.0). Even then it is just a matter of adjusting the source tag.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the general practice in conda forge is to point ot "official" releases on PyPi (so that it parallels what pip install does).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Of course, because that is what you want to have in the conda channel.

Now, if a user wants to compile a newer version of Slycot, say because there is a new feature in master or even in a PR that has not been released yet. Can he or she take the conda-forge recipe, use it for the checked out commit in question and install it in his or her environment? Sure. Question is, should we provide instructions for it or?


Additional tips for how to install Slycot from source can be found in the
``.travis.yml`` (commands used for Travis CI) and conda-recipe/ (conda
pre-requisites) both which are included in the source code repository.
On macOS you should use ``conda-recipe-apple``. See the
`conda-build documentation`_ how to get the required macOS SDK.

.. _conda-build documentation: https://docs.conda.io/projects/conda-build/en/latest/resources/compiler-tools.html#macos-sdk

For example, to build with the OpenBLAS recipe::

conda build -c conda-forge conda-recipe-openblas
conda install -c conda-forge --use-local slycot

From source in a conda environment (Windows)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A similar method can be used for Linux and macOS, but is detailed here
for Windows. This method uses conda and conda-forge to get most build
dependencies, *except* for the C compiler.

This procedure has been tested on Python 3.7 and 3.8.

The hardest part about installing from source is getting a working version of
FORTRAN and LAPACK installed on your system and working properly with Python.
On Windows, the build system currently uses flang, which can be installed from
conda-forge. Note that flang is incompatible with Python 2.7.
First, install the `correct Visual Studio compiler for the Python
version`_ you wish to build for.

If you are using conda, you can also get working (binary) copies of LAPACK from
conda-forge using the command::
.. _correct Visual Studio compiler for the Python version: https://wiki.python.org/moin/WindowsCompilers

conda install -c conda-forge lapack
To build, you'll need a command shell setup for both conda and the
Visual Studio build tools. See `conda activation`_ and `Microsoft
Visual Studio setup`_ for information on this.

Slycot will also work with the OpenBLAS libraries.
.. _conda activation: https://docs.conda.io/projects/conda/en/latest/user-guide/troubleshooting.html#windows-environment-has-not-been-activated
.. _Microsoft Visual Studio setup: https://docs.microsoft.com/en-us/cpp/build/setting-the-path-and-environment-variables-for-command-line-builds?view=vs-2019

In such a command shell, run the following commands to build and
install Slycot (this example creates a Python 3.8 environment)::

conda create --channel conda-forge --name build-slycot python=3.8 numpy scipy libblas=*=*netlib liblapack=*=*netlib scikit-build flang pytest
conda activate build-slycot

python setup.py install
pytest

The final ``pytest`` command is optional; it runs the Slycot unit tests.

General notes on compiling
~~~~~~~~~~~~~~~~~~~~~~~~~~

Additional tips for how to install Slycot from source can be found in the
``.travis.yml`` (commands used for Travis CI) and the ``conda-recipe-*/``
directories (conda pre-requisites) both which are included in the source
code repository.

The hardest part about installing from source is getting a working
version of FORTRAN and LAPACK (provided by OpenBLAS, MKL, etc.)
installed on your system, and working properly with Python.

Note that in some cases you may need to set the ``LIBRARY_PATH`` environment
variable to pick up dependencies such as ``-lpythonN.m`` (where N.m is the
version of python you are using).

Using pip
~~~~~~~~~

We publish Slycot to the Python package index, but only as a source
package, so to install using pip you'll first need to install the
build prerequisites (compilers, libraries, etc.)

If you have these build prerequisites, install in the standard way with:

pip install slycot
20 changes: 0 additions & 20 deletions conda-recipe-mkl/bld.bat

This file was deleted.

27 changes: 0 additions & 27 deletions conda-recipe-openblas/bld.bat

This file was deleted.