maint: merge conflicts with development branch resolved

.github/workflows/wheels.yml

@@ -50,15 +50,15 @@ jobs:
     uses: giganano/VICE/.github/workflows/bdist_macos.yml@main
     with:
       python-versions: >-
-        ["3.6", "3.7", "3.8", "3.9", "3.10"]
+        ["3.7", "3.8", "3.9", "3.10"]
       wheel-name: macos_x86_64
 
   ##### manylinux2014 distribution on x86_64 hardware #####
   manylinux2014_x86_64:
     uses: giganano/VICE/.github/workflows/bdist_linux.yml@main
     with:
       python-versions: >-
-        ["cp36-cp36m", "cp37-cp37m", "cp38-cp38", "cp39-cp39", "cp310-cp310"]
+        ["cp37-cp37m", "cp38-cp38", "cp39-cp39", "cp310-cp310"]
       wheel-name: manylinux2014_x86_64
       image: docker://quay.io/pypa/manylinux2014_x86_64
 
@@ -67,7 +67,7 @@ jobs:
     uses: giganano/VICE/.github/workflows/bdist_linux.yml@main
     with:
       python-versions: >-
-        ["cp36-cp36m", "cp37-cp37m", "cp38-cp38", "cp39-cp39", "cp310-cp310"]
+        ["cp37-cp37m", "cp38-cp38", "cp39-cp39", "cp310-cp310"]
       wheel-name: manylinux_2_24_x86_64
       image: docker://quay.io/pypa/manylinux_2_24_x86_64
 

docs/src/api/pkgcontents/gen/__main__.py

@@ -3,8 +3,8 @@
 """
 
 import sys
-if sys.version_info[:2] < (3, 6):
-	raise RuntimeError("Python >= 3.6 required to compile VICE documentation.")
+if sys.version_info[:2] < (3, 7):
+	raise RuntimeError("Python >= 3.7 required to compile VICE documentation.")
 else: pass
 
 import vice

docs/src/install.rst

@@ -269,6 +269,8 @@ would like help getting started, usage guidelines can be found
 
 .. 		$ python setup.py build ext=vice.core.singlezone._singlezone install [--user]
 
+=======
+>>>>>>> development
 
 Things to Avoid
 ---------------

migration/README.rst

@@ -41,12 +41,13 @@ can be found in the associated journal publication.
 
 Requirements
 ============
-To run these models, you must first `install the latest version of VICE`__,
-1.2.0. Unless you wish to modify VICE's source code to run some alternate
+To run these models, you must first `install VICE`__ version 1.2.0 or greater.
+Unless you wish to modify VICE's source code to run some alternate
 version of these models, you can achieve this with a simple ``pip install vice``
 command in a ``Unix`` terminal. VICE 1.2.0 is the earliest version that
 includes the necessary functionality with which to handle stellar migration.
-In turn, VICE 1.2.0 requires Python >= 3.6.0.
+In turn, VICE 1.2.0 requires Python >= 3.6.0, but subsequent versions require
+later versions of Python.
 
 __ install_
 .. _install: https://vice-astro.readthedocs.io/en/latest/install.html

setup.py

@@ -84,14 +84,14 @@
 # Changes to these numbers also require changes to ./docs/src/index.rst and
 # ./docs/src/cover.tex
 MAJOR			= 1
-MINOR			= 3
-MICRO			= 1
-DEV				= None
+MINOR			= 4
+MICRO			= 0
+DEV				= 0
 ALPHA			= None
 BETA			= None
 RC				= None
 POST			= None
-ISRELEASED		= True
+ISRELEASED		= False
 VERSION			= "%d.%d.%d" % (MAJOR, MINOR, MICRO)
 if DEV is not None:
 	assert isinstance(DEV, int), "Invalid version information"

vice/__init__.py

@@ -72,6 +72,8 @@
 	Read in stellar population abundances from a multizone simulation output.
 toolkit : <module>
 	Generally useful utilities.
+_dev : <module>
+	Developer's tools.
 
 Built-In Dataframes
 -------------------
@@ -125,6 +127,7 @@
 			"elements",
 			"yields",
 			"_globals",
+			"_dev",
 			"toolkit",
 			"ScienceWarning",
 			"VisibleRuntimeWarning",
@@ -155,6 +158,7 @@
 			from . import yields
 			from . import toolkit
 			from .tests import test
+			from . import _dev
 			__all__.extend(core.__all__)
 		except (ImportError, ModuleNotFoundError):
 			raise ImportError("""\

vice/_dev.py

@@ -0,0 +1,74 @@
+r"""
+**VICE Developer's Documentation**
+
+Developer's Toolkit
+
+Contents
+--------
+set_logging_level : ``function``
+	Adjust the amount of verbose output from VICE's backend for debugging and
+	development purposes.
+"""
+
+from __future__ import absolute_import
+from ._globals import _VERSION_ERROR_
+import sys
+import os
+if sys.version_info[:2] == (2, 7):
+	strcomp = basestring
+elif sys.version_info[:2] >= (3, 5):
+	strcomp = str
+else:
+	_VERSION_ERROR_()
+
+
+def set_logging_level(level = None):
+	r"""
+	Adjust the amount of verbose output from VICE's backend for debuggin and
+	development purposes.
+
+	**Signature**: vice._dev.set_logging_level(level = None)
+
+	Parameters
+	----------
+	level : ``str`` [case-insensitive] or ``None`` [default]
+		A string describing the level of output. ``None`` for no output at all.
+		Recognized values:
+
+			- "info"
+				Print only descriptive statements about the current calculation.
+			- "trace"
+				Print the names of functions being called and in which file the
+				function is implemented.
+			- "debug"
+				Print the names of functions being called, the files in which
+				they are implemented, the line numbers calling the logging print
+				statement, and variable states.
+
+	Notes
+	-----
+	This function works by setting the environment variable "VICE_LOGGING_LEVEL"
+	to "1", "2", or "3", integer values for which correspond to "info",
+	"trace", and "debug" logging. This environment variable is detected by
+	VICE's C library causing various functions to print (depending on the
+	logging level) info and/or variable states to stderr.
+	"""
+	if isinstance(level, strcomp):
+		# The values of the environment variables are #define'd in
+		# vice/src/debug.h along with other debugging macros.
+		if level.lower() == "info":
+			os.environ["VICE_LOGGING_LEVEL"] = "1"
+		elif level.lower() == "trace":
+			os.environ["VICE_LOGGING_LEVEL"] = "2"
+		elif level.lower() == "debug":
+			os.environ["VICE_LOGGING_LEVEL"] = "3"
+		else:
+			raise ValueError("Unrecognized logging level: %s" % (level))
+	elif level is None:
+		if "VICE_LOGGING_LEVEL" in os.environ.keys():
+			del os.environ["VICE_LOGGING_LEVEL"]
+		else: pass
+	else:
+		raise TypeError("""Logging level must be either ``str`` or ``None``. \
+Got: %s""" % (type(level)))
+

vice/src/callback.c

@@ -21,6 +21,7 @@
  */
 extern double callback_1arg_evaluate(CALLBACK_1ARG cb1, double x) {
 
+	// trace_print(); // significant slowdown
 	if (cb1.user_func != NULL) {
 		return cb1.callback(x, cb1.user_func);
 	} else {
@@ -47,6 +48,7 @@ extern double callback_1arg_evaluate(CALLBACK_1ARG cb1, double x) {
  */
 extern double callback_2arg_evaluate(CALLBACK_2ARG cb2, double x, double y) {
 
+	// trace_print(); // significant slowdown
 	if (cb2.user_func != NULL) {
 		return cb2.callback(x, y, cb2.user_func);
 	} else {

vice/src/debug.h

@@ -0,0 +1,136 @@
+/*
+ * This file handles logging within VICE for development and debugging
+ * purposes. VICE subscribes to a conventional format, where there are six
+ * different types of verbosity for logging:
+ * 
+ * 1. info: General information regarding the process executed by the program.
+ * 2. trace: Individual function calls and the files in which they're
+ *    implemented.
+ * 3. debug: Print the names of functions being called, the files in which
+ *    they're implemented, the line numbers calling the logging print statement,
+ *    and variable states.
+ * 4. warning: Prints regardless of the user's logging level and whether or not
+ *    they've ignored warnings in Python. Does not stop the program.
+ * 5. error: A state is reached in which VICE cannot continue the calculation.
+ *    This exits the python interpreter always.
+ * 6. fatal: A state is reached in which VICE cannot *safely* continue the
+ *    calculation. This exits the python interpreter always.
+ */
+
+#ifndef DEBUG_H
+#define DEBUG_H
+
+#include <stdlib.h>
+#include <string.h>
+#include <stdio.h>
+
+/*
+ * Failsafe: define the __func__ identifier if it isn't already for maximum
+ * portability.
+ */
+#if __STDC_VERSION__ < 199901L
+	#if __GNUC__ >= 2
+		#define __func__ __FUNCTION__
+	#else
+		#define __func__ "<unknown>"
+	#endif /* __GNUC__ */
+#endif /* __STDC_VERSION__ */
+
+/* Different level of verbosity within logging */
+#define INFO 1u
+#define TRACE 2u
+#define DEBUG 3u
+
+/*
+ * Determine the depth of VICE's verbose logging output by obtaining the
+ * integer value of the environment variable "VICE_LOG_LEVEL" - 1 for info,
+ * 2 for trace, and 3 for debug.
+ */
+#define logging_level() ({ \
+	char *_loglevel = getenv("VICE_LOGGING_LEVEL"); \
+	_loglevel != NULL ? atoi(_loglevel) : 0; \
+})
+
+/*
+ * Prints a statement to stderr if and only if the loglevel is equal to 1
+ * (INFO).
+ */
+#define info_print(fmt, ...) \
+	do { \
+		if (logging_level() == INFO) { \
+			fprintf(stderr, fmt, __VA_ARGS__); \
+		} else {} \
+	} while (0)
+
+/*
+ * Prints the name of the file and function that is being executed to stderr 
+ * if and only if the loglevel is equal to 2 (INFO).
+ */
+#define trace_print() \
+	do { \
+		if (logging_level() == TRACE) { \
+			fprintf(stderr, "%s:%d:%s()\n", __FILE__, __LINE__, __func__); \
+		} else {} \
+	} while (0)
+
+/*
+ * Print the value of variables to the console to stderr if and only if the
+ * loglevel is equal to 3 (DEBUG).
+ */
+#define debug_print(fmt, ...) \
+	do { \
+		if (logging_level() == DEBUG) { \
+			fprintf(stderr, "%s:%d:%s(): " fmt, __FILE__, __LINE__, __func__, \
+				__VA_ARGS__); \
+		} else {} \
+	} while (0)
+
+/* For printing errors and warning messages in red. */
+#define RESET "\033[0m"
+#define RED "\033[31m"
+#define BOLDRED "\033[1m\033[31m"
+
+/*
+ * Print a warning message to the console. This runs regardless of the logging
+ * level and whether or not the user has turned off Python warnings. This
+ * message is however intended for developers, so if this warning is raised in
+ * an end user's system where they haven't modified source code, it should be
+ * interpreted as an issue within VICE.
+ */
+#define warning_print(fmt, ...) \
+	do { \
+		fprintf(stderr, RED"Warning: "RESET fmt, __VA_ARGS__); \
+	} while (0)
+
+/*
+ * Raise an error message to the console and exit the current process; this
+ * will quit the Python interpreter. This runs regardless of the logging
+ * level and whether or not the user has turned off Python warnings. This
+ * message is however intended for developers, so if this warning is raised in
+ * an end user's system where they haven't modified source code, it should be
+ * interpreted as an issue within VICE.
+ */
+#define error_print(fmt, ...) \
+	do { \
+		fprintf(stderr, BOLDRED"Error!"RESET" %s:%d:%s(): " fmt, \
+			__FILE__, __LINE__, __func__, __VA_ARGS__); \
+		exit(1); \
+	} while (0)
+
+/*
+ * Raise a fatal message to the console and exit the current process; this
+ * will quit the Python interpreter. This runs regardless of the logging
+ * level and whether or not the user has turned off Python warnings. This
+ * message is however intended for developers, so if this warning is raised in
+ * an end user's system where they haven't modified source code, it should be
+ * interpreted as an issue within VICE.
+ */
+#define fatal_print(fmt, ...) \
+	do { \
+		fprintf(stderr, BOLDRED"Fatal!"RESET" %s:%d:%s(): " fmt, \
+			__FILE__, __LINE__, __func__, __VA_ARGS__); \
+		exit(1); \
+	} while (0)
+
+#endif /* DEBUG_H */
+