diff --git a/README.md b/README.md index 7a547cd..d79ae38 100644 --- a/README.md +++ b/README.md @@ -4,68 +4,134 @@ Introduction This is the Python MsSpec version with support for Python 3.x and dynamic memory allocation for Phagen and Spec +Installation of the devel package +================================= -To work with the git repository -=============================== +Requirements +------------ -You can clone this repository onto your local computer using git +To compile MsSpec shared libraries, you need: + + - Python >= 3.6 + - gfortran compiler + - cairo library (runtime files and header files) + +Depending on your OS and Python version, you may need all the requirements (runtime libraries +and header files) to build wxPython (please consult your distribution's package list for the +appropriate package names) and their dependencies: + + - python-dev (for your version of python) + - gtk (preferably version 3, but depends on your needs) + - gstreamer + - gstreamer-plugins-base + - glut + - libwebkitgtk (matching your gtk version) + - libjpeg + - libpng + - libtiff + - libsdl + - libnotify + - libsm + +You also need a tool to create and manage Python virtual environments. For now only +*virtualenv* is supported. So if you plan to install msspec with the one-step command, +you need to install it. + + + +Fetching the code +----------------- + +You first need to clone the devel branch with either 2 commands below: ```Bash git clone https://git.ipr.univ-rennes1.fr/epsi/msspec_python3.git +git checkout devel ``` -This will create a folder named "msspec_python3" with all the source code inside. - -You can also clone the development branch: - ```Bash git clone --branch devel https://git.ipr.univ-rennes1.fr/epsi/msspec_python3.git ``` +This will create a msspec\_python3 folder with a local copy of the repository. -It is higly recommended to work in a Python virtual environment. -To create one, you can use: + + +One step install +---------------- + +The command below will do all the stuff to install msspec in its dedicated Python +virtual environment provided all the above requirements are fullfilled ```Bash -virtualenv --python=python3 msspec_venv +cd msspec_python3 +make devel ``` -or +This will: + - Create a Python virtual environment in the "\_venv" folder inside the msspec\_python3 folder. + - Install all the required Python packages in this virtual environment. + - Install (or even maybe build) wxPython for your OS and Python version in this virtual environment. + - Build the msspec shared librarires. + - Install msspec in *edit mode* in this virtual environment. + +You can tweak the process by specifying space separated key=value pairs on the command line. +Allowed keys are: + + - PYTHON, to give the executable name of the python interpreter to use rather than the default (python) + - VERBOSE, set to 1 if you want the install process to be more verbose + - NO\_VENV, set to 1 to not create a virtual environment + - VENV\_PATH, specify the path to a virtual environment root folder + - DEBUG, set to 1 to add debugging symbols + - BUILDDIR, to set a different name than the default to store building artifacts (./build) + - FC, the Fortran compiler to use (gfortran) + - F2PY + + +Work with msspec +---------------- + +All you need to do each time you want to work with msspec is activating the virtual environment. + +For example, if *virtualenv* was used to create the virtual environment: ```Bash -virtualenv --python=python3 --system-site-packages msspec_venv +source msspec_python3/_venv/bin/activate ``` -to activate the virtual environment (if you are in the folder where you created "msspec\_venv"): +Then you can launch your script with ```Bash -source ./msspec_venv/bin/activate +python myscript.py ``` -Now you can build the program, go in the source folder +See the online [tutorials](https://msspec.cnrs.fr/tutorials/index.html) for more information on how to use msspec. + +When you're done, you can deactivate the virtual environment with ```Bash -cd msspec_python3/src +deactivate ``` -Install the python package dependencies. +Uninstall MsSpec +---------------- -```Bash -pip install -r setup_requirements.txt -pip install -r requirements.txt -``` +When Installed in "devel mode", nothing is created outside the msspec\_python3 folder, so you just have to remove +that folder to get rid of msspec on your computer -You need to compile the fortran libs. This is done by the scons (Software Construction) program -```Bash -scons -``` +Manual control over the install +------------------------------- -Finally, install the package in develop mode: +If for any reason you want to control each step of the building process (for example you do not have *virtualenv* but you +are using *conda*), here is how: -```Bash -pip install -e . -``` + - Create a virtual environment or use an existing one and activate it + - Install the list of requirements that are listed in the src/pip.freeze file + - Install wxPython + - Build the msspec shared librarires with the command "make pybinding" + - Install the msspec Python package with "pip install -e src/" -That's all. All you need to do each time you want to work with msspec is activating the virtual environment +The last step can be replaced by adding the src/ path to your PYTHONPATH, but bear in mind that the package will then +be also visible to other virtual environments no matter they fit the msspec requirements. diff --git a/src/Makefile.old b/src/Makefile.old deleted file mode 100644 index a7cc556..0000000 --- a/src/Makefile.old +++ /dev/null @@ -1,60 +0,0 @@ -VERSION:=$(shell python -c "import msspec; print(msspec.__version__)") - -VERBOSE:=0 -ifeq ($(VERBOSE),0) - SUPPRESS_OUPUT:=1>/dev/null 2>/dev/null - MAKEFLAGS += --no-print-directory --silent -else - SUPPRESS_OUPUT:= -endif - - -install: sdist - @echo "Installing the newly created Python package..." - @pip install dist/msspec-*.tar.gz $(SUPPRESS_OUPUT) - -sdist: install_deps - @echo "Creating Python source distribution..." -# Create the source distrib - @python setup.py sdist $(SUPPRESS_OUPUT) - -install_deps: pybinding - @echo "Installing Python dependencies..." -# Install dependencies with pip - @pip install --upgrade -r requirements.txt $(SUPPRESS_OUPUT) - -pybinding: - @echo "Building Python binding for phagen and spec..." - @+$(MAKE) -C msspec/spec/fortran pybinding $(SUPPRESS_OUPUT) - @+$(MAKE) -C msspec/phagen/fortran pybinding $(SUPPRESS_OUPUT) - -results: msspec/results.txt - -msspec/results.txt: pybinding - @echo "Generating results for unittests" - @coverage run --source=./ --omit=msspec/es/*,msspec/msspecgui/* msspec/create_tests_results.py 1>/dev/null -# create the html coverage report - @coverage html -d ../doc/source/htmlcov - @rm .coverage - -tests: pybinding - @echo "Runing unittests" - @python -m msspec.tests 1>/dev/null - -clean: - @echo "Cleaning all..." - @find ./ -type f -name '*.pyc' -exec rm -f {} + - @find ./ -type d -name '__pycache__' -exec rm -rf {} + - @+$(MAKE) -C msspec/spec/fortran clean $(SUPPRESS_OUPUT) - @+$(MAKE) -C msspec/phagen/fortran clean $(SUPPRESS_OUPUT) -# remove previous sdist - @rm -rf dist - @rm -rf *.egg* - -purge: clean - @echo "Removing also shared objects..." - @find ./ -type f -name '*.so' -exec rm -f {} + - -help: - @echo "help message" - diff --git a/src/SConstruct b/src/SConstruct deleted file mode 100644 index 3739618..0000000 --- a/src/SConstruct +++ /dev/null @@ -1,125 +0,0 @@ -import os -import subprocess -import datetime -from pkg_resources import parse_version -from setuptools_scm import get_version - -############################################################################### -def filtered_glob(env, pattern, omit=[], - ondisk=True, source=False, strings=False): - return list(filter( - lambda f: os.path.basename(f.path) not in omit, - env.Glob(pattern))) - -# Create a builder for f2py -def f2py_generator(source, target, env, for_signature): - suffix = ".so" - main = source[0] - objects = " ".join(o.get_path() for o in source[1:] if str(o).endswith('.o')) - moduledir = os.path.dirname(target[0].abspath) - modulefile = str(target[0]) - modulename = modulefile.replace(suffix, '').replace('/', '.') - compiler = env['FORTRAN'] - - cmd = f"$F2PY --fcompiler={compiler} " - cmd += f" $F2PY_OPTS -m {modulename} -c {objects} {main}" - cmd += f" && cp {'/'.join(modulename.split('.'))}.*.so {modulefile}" - #cmd += " 1>/dev/null 2>/dev/null" - return cmd - -def install_module(env, module): - destdir = os.path.dirname(module[0].srcnode().abspath) - env.Install(destdir, module) - env.Alias('install', destdir) - return None - -def version_action(target, source, env): - with open(str(target[0]), 'w') as fd: - v = get_version(root='../', relative_to='./', version_scheme="post-release") - v = parse_version(v) - if v._version.post[-1] == 0: - version = v.base_version - else: - version = v.public - fd.write(version + '\n') - now = datetime.datetime.now().isoformat() - fd.write(f'compiled on {now}\n') - p = subprocess.run([env['FORTRAN'], "--version"], stdout=subprocess.PIPE) - fd.write(p.stdout.decode('utf8')) - - -f2py_bld = Builder(generator=f2py_generator) -version_bld = Builder(action=version_action) - -# define the default build environment -std = Environment(tools=['default', 'fortran'], F2PY_OPTS=[], LIBS=[]) -std.AddMethod(filtered_glob, "FilteredGlob") -std.AddMethod(install_module, "InstallModule") -std['BUILDERS']['F2py'] = f2py_bld -std['BUILDERS']['Version'] = version_bld - -############################################################################### - -# Define the command line options -AddOption('--dbg', - dest='dbg', - action='store_true', - help='add debugging symbols') - -AddOption('--verbose', - dest='verbose', - action='store_true', - help='add debugging symbols') - -AddOption('--compiler', - dest='compiler', - default='gfortran', - choices=['gfortran', 'ifort'], - help='The Fortran compiler to use') - -AddOption('--f2py_path', - dest='f2py_path', - default='f2py3', - help='The full path to the f2py compiler') - - - -# define environments -gfortran_env = std.Clone(tools=['gfortran']) -#gfortran_env.Replace(FORTRANFLAGS=['-fPIC', '-O2', '-ffast-math', '-mcmodel=large', '-fdefault-real-8', '-fdefault-double-8']) -gfortran_env.Replace(FORTRANFLAGS=['-fPIC', '-mcmodel=large']) - -ifort_env = std.Clone(tools=['ifort']) - -# parse options -if GetOption('compiler') == 'gfortran': - env = gfortran_env - #env.Append(F2PY_OPTS='--opt=-O2') -elif GetOption('compiler') == 'ifort': - env = ifort_env - -f2py_path = GetOption('f2py_path') -p = subprocess.run(['which', f2py_path], stdout=subprocess.PIPE) -if p.returncode != 0: - raise Exception('Invalid path for f2py compiler!') -else: - env.Append(F2PY=p.stdout.decode('utf8').strip()) - -if GetOption('dbg'): - flags = ['-g', '-Wall', '-Wextra', '-Warray-temporaries', - '-Wconversion', '-fbacktrace', '-ffree-line-length-0', - '-fcheck=all', '-ffpe-trap=zero,overflow,underflow,invalid,denormal', - '-finit-real=nan'] - gfortran_env.Append(FORTRANFLAGS = flags, - F2PY_OPTS = ['--noopt', '--debug-capi', '--debug', '--f77flags=-g -fcheck=all -fbacktrace -ffpe-trap=zero,overflow,underflow,invalid,denormal']) - -if GetOption('verbose'): - env.Replace(FORTRANCOMSTR = "") - - -Export('env') -SConscript('msspec/spec/fortran/SConstruct', variant_dir='build/build_spec') -SConscript('msspec/phagen/fortran/SConstruct', variant_dir='build/build_phagen') - -version_file = env.Version('VERSION', []) -Depends(version_file, "install") diff --git a/src/msspec/phagen/fortran/SConstruct b/src/msspec/phagen/fortran/SConstruct deleted file mode 100644 index 3716a3d..0000000 --- a/src/msspec/phagen/fortran/SConstruct +++ /dev/null @@ -1,10 +0,0 @@ -Import('env') -import os - -objects_src= ['phagen_scf_2.1_dp.f'] -objects = env.Object(objects_src) - -module = env.F2py('libphagen.so', ['main.f'] + objects, F2PYCOMSTR=">>") -env.InstallModule(module) - -env.Alias('phagen', module) diff --git a/src/msspec/spec/fortran/SConstruct b/src/msspec/spec/fortran/SConstruct deleted file mode 100644 index a362411..0000000 --- a/src/msspec/spec/fortran/SConstruct +++ /dev/null @@ -1,71 +0,0 @@ -Import('env') -import os - -# Configure the environment -env_spec = env.Clone() -cwd = Dir('.').get_abspath() -env_spec.Append(FORTRANFLAGS=['-I' + cwd,'-J' + cwd]) -env_spec.Append(F2PY_OPTS=['-I' + cwd]) - -# define sources -dim_mod = ['memalloc/dim_mod.f'] -memalloc = ['memalloc/modules.f', 'memalloc/allocation.f'] -cluster_gen = Glob('cluster_gen/*.f') -common_sub = Glob('common_sub/*.f') -renormalization = Glob('renormalization/*.f') -phd_se_noso_nosp_nosym = env_spec.FilteredGlob('phd_se_noso_nosp_nosym/*.f', omit=['main.f']) -phd_mi_noso_nosp_nosym = env_spec.FilteredGlob('phd_mi_noso_nosp_nosym/*.f', omit=['main.f']) -eig_common = Glob('eig/common/*.f') -eig_mi = env_spec.FilteredGlob('eig/mi/*.f', omit=['main.f']) -eig_pw = env_spec.FilteredGlob('eig/pw/*.f', omit=['main.f']) -comp_curves = ['treatment/comp_curves.f'] - -conf = Configure(env_spec, log_file='./config.log') -if conf.CheckLib('lapack'): - env_spec.Append(F2PY_OPTS = "-llapack") - eig_mi = [f for f in eig_mi if str(f).find('lapack') == -1] - phd_mi_noso_nosp_nosym = [f for f in phd_mi_noso_nosp_nosym if str(f).find('lapack') == -1] -env_spec = conf.Finish() -env_spec.Append(FORTRANFLAGS='-fno-automatic') - -# define objects -dim_mod_obj = env_spec.Object(dim_mod) -memalloc_obj = env_spec.Object(memalloc) -cluster_gen_obj = env_spec.Object(cluster_gen) -common_sub_obj = env_spec.Object(common_sub) -renormalization_obj = env_spec.Object(renormalization) -phd_se_noso_nosp_nosym_obj = env_spec.Object(phd_se_noso_nosp_nosym) -phd_mi_noso_nosp_nosym_obj = env_spec.Object(phd_mi_noso_nosp_nosym) -eig_common_obj = env_spec.Object(eig_common) -eig_pw_obj = env_spec.Object(eig_pw) -eig_mi_obj = env_spec.Object(eig_mi) -comp_curves_obj = env_spec.Object(comp_curves) - -Requires(memalloc_obj, dim_mod_obj) - -# define Python extensions -common_deps = dim_mod_obj + memalloc_obj + cluster_gen_obj + common_sub_obj - -deps = common_deps + renormalization_obj + phd_se_noso_nosp_nosym_obj -phd_se_mod = env_spec.F2py('_phd_se_noso_nosp_nosym.so', ['phd_se_noso_nosp_nosym/main.f'] + deps) -env_spec.InstallModule(phd_se_mod) - -deps = common_deps + renormalization_obj + phd_mi_noso_nosp_nosym_obj -phd_mi_mod = env_spec.F2py('_phd_mi_noso_nosp_nosym.so', ['phd_mi_noso_nosp_nosym/main.f'] + deps) -env_spec.InstallModule(phd_mi_mod) - -deps = common_deps + renormalization_obj + eig_common_obj + eig_mi_obj -eig_mi_mod = env_spec.F2py('_eig_mi.so', ['eig/mi/main.f'] + deps) -env_spec.InstallModule(eig_mi_mod) - -deps = common_deps + renormalization_obj + eig_common_obj + eig_pw_obj -eig_pw_mod = env_spec.F2py('_eig_pw.so', ['eig/pw/main.f'] + deps) -env_spec.InstallModule(eig_pw_mod) - -deps = comp_curves_obj -comp_curve_mod = env_spec.F2py('_comp_curves.so', ['treatment/main.f'] + deps) -env_spec.InstallModule(comp_curve_mod) - -# Alias -env_spec.Alias('spec', [phd_se_mod, phd_mi_mod, eig_pw_mod, eig_mi_mod]) -