From 6671835d7bd4aa959b4c7d50f83e7e94c765e650 Mon Sep 17 00:00:00 2001 From: anniegbryant Date: Thu, 22 Dec 2022 15:58:29 -0500 Subject: [PATCH 1/2] Add Java JVM DLL issue FAQ --- docs/source/faq.rst | 80 ++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 6 ++- docs/source/installation.rst | 38 +++++++++++++++++ docs/source/usage.rst | 30 -------------- 4 files changed, 122 insertions(+), 32 deletions(-) create mode 100644 docs/source/faq.rst create mode 100644 docs/source/installation.rst diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..7957c79 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,80 @@ +Issues & FAQ +=================================== + + +FAQ +######## + +Issues +######## + + +Java JVM DLL not found (specific to Mac) +********************** + +One user reported the following error when installing `pyspi` on a MacBook Air an M2 chip and Catalina OS: + +.. code-block:: + + OSError: [Errno 0] JVM DLL not found /Library/Java/JavaVirtualMachines/jdk-19.jdk/Contents/Home/lib/libjli.dylib + + +This issue is similar to those reported `here `_ and `here `_. This issue can arise from the version of OpenJDK identified as the system default + +We recommend following this `helpful tutorial `_ by Chamika Kasun to install `AdoptOpenJDK `_. In a nutshell, here are the steps you should run: + +Install homebrew if you don't already have it: + +.. code-block:: + + $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + + +Install `jenv` as your Java version manager: + +.. code-block:: + $ brew install jenv + + +Add `jenv` to your shell's configuration file (e.g. `.bashrc` if you use `bash`): + +.. code-block:: + $ export PATH="$HOME/.jenv/bin:$PATH" + $ eval "$(jenv init -)" + +Source your shell's configuration file: + +.. code-block:: + $ source ~/.bashrc # If you use bash + +Confirm proper installation of `jEnv`: + +.. code-block:: + $ jenv doctor + +Even if this returns some errors, as long as you see `Jenv is correctly loaded`, you're all set. We recommend using `AdoptOpenJDK` version 11, which you can install with the following command: + +.. code-block:: + $ brew install AdoptOpenJDK/openjdk/adoptopenjdk11 + +Now, you will need to add your `AdoptOpenJDK` path to your `jEnv` environments. First, you can find where your jdk files are installed with the following command: + +.. code-block:: + $ /usr/libexec/java_home -V + +This will list all your installed java JDK versions. Locate the one for `AdoptOpenJDK` version 11 and paste the path: + +.. code-block:: + $ jenv add + +Confirm `AdoptOpenJDK` version 11 was added to `jEnv`: + +.. code-block:: + $ jenv versions + +You can set `AdoptOpenJDK` version 11 as your global Java version with the following: + +.. code-block:: + $ jenv global + $ # example: + $ jenv global 11.0 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 88c8549..1b49308 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,7 +1,7 @@ Welcome to PySPI's documentation! =================================== -**PySPI** (/pie'spy/) is a Python library for simultaneously evaluating hundreds of pairwise interactions directly from multivariate time-series data. +**pyspi** (/pie'spy/) is a Python library for simultaneously evaluating hundreds of pairwise interactions directly from multivariate time-series data. It provides easy access to over 250 methods for evaluating the relationship between pairs of time series, from simple statistics (like correlation coefficients) to advanced multi-step algorithms (like Granger causality). @@ -16,6 +16,8 @@ Contents .. toctree:: + installation usage advanced - api \ No newline at end of file + api + faq \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..ca62bf8 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,38 @@ +Installation +=================================== + +Pre-installation +---------------- + +The code requires GNU's `Octave `_ by default, which is freely available on all popular operating systems. +See the `installation instructions `_ to find out how to install Octave on your system. + +.. note:: + You can safely install `pyspi` without first installing Octave but you will not have access to the `Integrated Information Theory` statistics, see :ref:`Using the toolkit without Octave`. + +While you can also install `pyspi` outside of a `conda `_ environment, it depends on a lot of user packages that may make managing dependencies quite difficult. +So, we would also recommend installing `pyspi` in a conda environment. +After `installing conda `_, create a new environment for using the toolkit: + +.. code-block:: console + + $ conda create -n pyspi python=3.9.0 + $ conda activate pyspi + + +Installation +------------ + +Next, download or clone the `latest version `_ from GitHub, unpack and install: + +.. code-block:: console + + $ git clone https://github.com/olivercliff/pyspi.git + $ cd pyspi + $ pip install . + +You can confirm that `pyspi` and dependencies installed properly with the following command: + +.. code-block:: console + + $ setup.py test \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 76e73c8..1dea594 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,36 +1,6 @@ Usage ===== -Pre-installation ----------------- - -The code requires GNU's `Octave `_ by default, which is freely available on all popular operating systems. -See the `installation instructions `_ to find out how to install Octave on your system. - -.. note:: - You can safely install `PySPI` without first installing Octave but you will not have access to the `Integrated Information Theory` statistics, see :ref:`Using the toolkit without Octave`. - -While you can also install `PySPI` outside of a `conda `_ environment, it depends on a lot of user packages that may make managing dependencies quite difficult. -So, we would also recommend installing `PySPI` in a conda environment. -After `installing conda `_, create a new environment for using the toolkit: - -.. code-block:: console - - $ conda create -n pyspi python=3.9.0 - $ conda activate pyspi - - -Installation ------------- - -Next, download or clone the `latest version `_ from GitHub, unpack and install: - -.. code-block:: console - - $ git clone https://github.com/olivercliff/pyspi.git - $ cd pyspi - $ pip install . - Getting Started --------------- From 10541fdc7be3bd445ab91c827d3f932a5f8d8961 Mon Sep 17 00:00:00 2001 From: anniegbryant Date: Fri, 6 Jan 2023 17:08:51 +1100 Subject: [PATCH 2/2] Fix code block indents and pyspi stylization --- docs/source/conf.py | 6 +++--- docs/source/faq.rst | 11 ++++++++++- docs/source/index.rst | 2 +- 3 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index f6f09f9..a6e8f6c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,12 +2,12 @@ # -- Project information -project = 'PySPI' +project = 'pyspi' copyright = '2022, Oliver M. Cliff' author = 'Oliver M. Cliff' -release = '0.3' -version = '0.3.0' +release = '0.4' +version = '0.4.0' # -- General configuration diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 7957c79..bed3b61 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -19,7 +19,7 @@ One user reported the following error when installing `pyspi` on a MacBook Air a OSError: [Errno 0] JVM DLL not found /Library/Java/JavaVirtualMachines/jdk-19.jdk/Contents/Home/lib/libjli.dylib -This issue is similar to those reported `here `_ and `here `_. This issue can arise from the version of OpenJDK identified as the system default +This issue is similar to those reported `here `_ and `here `_; it can arise from the version of OpenJDK identified as the system default. Some Java versions don't include all of the binary (DLL) files that `pyspi` looks for. We recommend following this `helpful tutorial `_ by Chamika Kasun to install `AdoptOpenJDK `_. In a nutshell, here are the steps you should run: @@ -33,48 +33,57 @@ Install homebrew if you don't already have it: Install `jenv` as your Java version manager: .. code-block:: + $ brew install jenv Add `jenv` to your shell's configuration file (e.g. `.bashrc` if you use `bash`): .. code-block:: + $ export PATH="$HOME/.jenv/bin:$PATH" $ eval "$(jenv init -)" Source your shell's configuration file: .. code-block:: + $ source ~/.bashrc # If you use bash Confirm proper installation of `jEnv`: .. code-block:: + $ jenv doctor Even if this returns some errors, as long as you see `Jenv is correctly loaded`, you're all set. We recommend using `AdoptOpenJDK` version 11, which you can install with the following command: .. code-block:: + $ brew install AdoptOpenJDK/openjdk/adoptopenjdk11 Now, you will need to add your `AdoptOpenJDK` path to your `jEnv` environments. First, you can find where your jdk files are installed with the following command: .. code-block:: + $ /usr/libexec/java_home -V This will list all your installed java JDK versions. Locate the one for `AdoptOpenJDK` version 11 and paste the path: .. code-block:: + $ jenv add Confirm `AdoptOpenJDK` version 11 was added to `jEnv`: .. code-block:: + $ jenv versions You can set `AdoptOpenJDK` version 11 as your global Java version with the following: .. code-block:: + $ jenv global $ # example: $ jenv global 11.0 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 1b49308..101e7b3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,4 @@ -Welcome to PySPI's documentation! +Welcome to pyspi's documentation! =================================== **pyspi** (/pie'spy/) is a Python library for simultaneously evaluating hundreds of pairwise interactions directly from multivariate time-series data.