Metadata-Version: 2.1
Name: lincs
Version: 0.10.2
Summary: Learn and Infer Non Compensatory Sortings
Home-page: https://github.com/MICS-Lab/lincs
Author: Vincent Jacques
Author-email: vincent@vincent-jacques.net
License: LGPLv3
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Description-Content-Type: text/x-rst
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: click~=8.1
Requires-Dist: matplotlib~=3.5

.. Copyright 2023 Vincent Jacques

.. This README is rendered to HTML in several places
    - on GitHub (https://github.com/mics-lab/lincs/)
    - on PyPI after publication of the package (https://pypi.org/project/lincs/)
    - on GitHub Pages (https://mics-lab.github.io/lincs/)
    So when you change it, take care to check all those places.

*lincs* (Learn and Infer Non Compensatory Sortings) is a collection of `MCDA <https://en.wikipedia.org/wiki/Multiple-criteria_decision_analysis>`_ algorithms, usable as a command-line utility.

@todo(Feature, later) Make it usable as a Python package.

@todo(Feature, later) Make it usable as a C++ library.

*lincs* supports Linux, macOS and Windows, with the exception that GPU-based algorithms are not available on macOS, because CUDA itself is not available there.

*lincs* is licensed under the GNU Lesser General Public License v3.0 as indicated by the two files `COPYING <https://github.com/MICS-Lab/lincs/blob/v0.10.2/COPYING>`_ and `COPYING.LESSER <https://github.com/MICS-Lab/lincs/blob/v0.10.2/COPYING.LESSER>`_.

@todo(Project management, when we publish a paper, later) Add a note asking academics to kindly cite our work.

*lincs* is available for install from the `Python package index <https://pypi.org/project/lincs/>`_.
Its `documentation <http://mics-lab.github.io/lincs/>`_
and its `source code <https://github.com/mics-lab/lincs/>`_ are on GitHub.

Questions? Remarks? Bugs? Want to contribute? Open `an issue <https://github.com/MICS-Lab/lincs/issues>`_ or `a discussion <https://github.com/MICS-Lab/lincs/discussions>`_!


Contributors
============

*lincs* is developed by the `MICS <https://mics.centralesupelec.fr/>`_ research team at `CentraleSupélec <https://www.centralesupelec.fr/>`_.

Its main authors are (alphabetical order):

- `Laurent Cabaret <https://cabaretl.pages.centralesupelec.fr/>`_ (performance optimization)
- `Vincent Jacques <https://vincent-jacques.net>`_ (engineering)
- `Vincent Mousseau <https://www.centralesupelec.fr/fr/2EBDCB86-64A4-4747-96E8-C3066CB61F3D>`_ (domain expertise)
- `Wassila Ouerdane <https://wassilaouerdane.github.io/>`_ (domain expertise)


Project goals
=============

Provide MCDA tools usable out of the box
----------------------------------------

You should be able to use *lincs* without being a specialist of MCDA and/or NCS models.
Just follow the "Get started" section below.

Provide a base for developing new MCDA algorithms
-------------------------------------------------

*lincs* is designed to be easy to extend with new algorithms of even replace parts of existing algorithms.
See our `contributor guide <https://mics-lab.github.io/lincs/contributor-guide.html>`_ for more details.


Get started
===========

Depending on your favorite approach, you can either start with our `hands-on "Get started" guide <https://mics-lab.github.io/lincs/get-started.html>`_
or with our `conceptual overview documentation <https://mics-lab.github.io/lincs/conceptual-overview.html>`_.
The former will show you how to use our tools, the latter will explain the concepts behind them: what's MCDA, what are NCS models, *etc.*
If in doubt, start with the conceptual overview.
We highly recommend you read the other one just after.

Once you've used *lincs* a bit, you can follow up with our `user guide <https://mics-lab.github.io/lincs/user-guide.html>`_
and `reference documentation <https://mics-lab.github.io/lincs/reference.html>`_.


Versioning
==========

Starting with version 1.0.0, *lincs* uses `semantic versioning <https://semver.org/>`_.

*lincs*' public API (that "must be declared" according to SemVer) is constituted exclusively by its `reference documentation <https://mics-lab.github.io/lincs/reference.html>`_,
**at a code level**: we consider a change as backward compatible if the client code doesn't need to be modified to keep working,
even if that change requires recompiling the client code in some cases.

Future backward compatible changes might change *lincs*' behavior, especially with regards to pseudo-random behavior.

Note that we plan to make *lincs* usable as Python and C++ libraries.
When we do that, we'll add these interfaces to the public API.
In the mean time, if you chose to use *lincs* that way, you must expect unanticipated changes to these interfaces.

Exceptions
----------

Default values
^^^^^^^^^^^^^^

Default values of optional arguments are not considered part of the public API.
They might change in future releases if we find values that perform better for most use-cases.

We advice you write your scripts in an explicit way where it matters to you,
and rely on implicit default values only where you want the potential future improvements.

File formats
^^^^^^^^^^^^

The same specification applies to files read and produced by *lincs*.
This leads to an issue about backward compatibility:
if we allow more flexibility in input files, new versions of *lincs* will be able to read both the old and the new format, in a backward-compatible way.
But if *lincs* produces a file in the new format, existing client scripts might not be able to read it, making this change backward-incompatible.

To solve this issue, we impose an additional constraint to *lincs*' public API:
*lincs* will produce files in a new format only when the client uses the new feature that motivated the new format.

That way, we know that the client already needs to modify their scripts, so they can adapt to the new format.


Develop *lincs* itself
======================

See our `contributor guide <https://mics-lab.github.io/lincs/contributor-guide.html>`_.
