MAINT: Merge branch 'main' into delete-speedup

38 files changed, 864 insertions, 0 deletions

diff --git a/doc/source/f2py/code/CMakeLists.txt b/doc/source/f2py/code/CMakeLists.txt
new file mode 100644
index 000000000..d16ddf77e
--- /dev/null
+++ b/doc/source/f2py/code/CMakeLists.txt
@@ -0,0 +1,65 @@
+cmake_minimum_required(VERSION 3.18) # Needed to avoid requiring embedded Python libs too
+
+project(fibby
+  VERSION 1.0
+  DESCRIPTION "FIB module"
+  LANGUAGES C Fortran
+)
+
+# Safety net
+if(PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR)
+  message(
+    FATAL_ERROR
+      "In-source builds not allowed. Please make a new directory (called a build directory) and run CMake from there.\n"
+  )
+endif()
+
+# Grab Python, 3.7 or newer
+find_package(Python 3.7 REQUIRED
+  COMPONENTS Interpreter Development.Module NumPy)
+
+# Grab the variables from a local Python installation
+# F2PY headers
+execute_process(
+  COMMAND "${Python_EXECUTABLE}"
+  -c "import numpy.f2py; print(numpy.f2py.get_include())"
+  OUTPUT_VARIABLE F2PY_INCLUDE_DIR
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
+# Print out the discovered paths
+include(CMakePrintHelpers)
+cmake_print_variables(Python_INCLUDE_DIRS)
+cmake_print_variables(F2PY_INCLUDE_DIR)
+cmake_print_variables(Python_NumPy_INCLUDE_DIRS)
+
+# Common variables
+set(f2py_module_name "fibby")
+set(fortran_src_file "${CMAKE_SOURCE_DIR}/fib1.f")
+set(f2py_module_c "${f2py_module_name}module.c")
+
+# Generate sources
+add_custom_target(
+  genpyf
+  DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}"
+)
+add_custom_command(
+  OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}"
+  COMMAND ${Python_EXECUTABLE}  -m "numpy.f2py"
+                   "${fortran_src_file}"
+                   -m "fibby"
+                   --lower # Important
+  DEPENDS fib1.f # Fortran source
+)
+
+# Set up target
+Python_add_library(${CMAKE_PROJECT_NAME} MODULE WITH_SOABI
+  "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}" # Generated
+  "${F2PY_INCLUDE_DIR}/fortranobject.c" # From NumPy
+  "${fortran_src_file}" # Fortran source(s)
+)
+
+# Depend on sources
+target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE Python::NumPy)
+add_dependencies(${CMAKE_PROJECT_NAME} genpyf)
+target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE "${F2PY_INCLUDE_DIR}")
diff --git a/doc/source/f2py/code/CMakeLists_skbuild.txt b/doc/source/f2py/code/CMakeLists_skbuild.txt
new file mode 100644
index 000000000..3d092760b
--- /dev/null
+++ b/doc/source/f2py/code/CMakeLists_skbuild.txt
@@ -0,0 +1,95 @@
+### setup project ###
+cmake_minimum_required(VERSION 3.9)
+
+project(fibby
+  VERSION 1.0
+  DESCRIPTION "FIB module"
+  LANGUAGES C Fortran
+  )
+
+# Safety net
+if(PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR)
+  message(
+    FATAL_ERROR
+      "In-source builds not allowed. Please make a new directory (called a build directory) and run CMake from there.\n"
+  )
+endif()
+
+# Ensure scikit-build modules
+if (NOT SKBUILD)
+  find_package(PythonInterp 3.7 REQUIRED)
+  # Kanged --> https://github.com/Kitware/torch_liberator/blob/master/CMakeLists.txt
+  # If skbuild is not the driver; include its utilities in CMAKE_MODULE_PATH
+  execute_process(
+    COMMAND "${PYTHON_EXECUTABLE}"
+    -c "import os, skbuild; print(os.path.dirname(skbuild.__file__))"
+    OUTPUT_VARIABLE SKBLD_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+  )
+  list(APPEND CMAKE_MODULE_PATH "${SKBLD_DIR}/resources/cmake")
+  message(STATUS "Looking in ${SKBLD_DIR}/resources/cmake for CMake modules")
+endif()
+
+# scikit-build style includes
+find_package(PythonExtensions REQUIRED) # for ${PYTHON_EXTENSION_MODULE_SUFFIX}
+
+# Grab the variables from a local Python installation
+# NumPy headers
+execute_process(
+  COMMAND "${PYTHON_EXECUTABLE}"
+  -c "import numpy; print(numpy.get_include())"
+  OUTPUT_VARIABLE NumPy_INCLUDE_DIRS
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+# F2PY headers
+execute_process(
+  COMMAND "${PYTHON_EXECUTABLE}"
+  -c "import numpy.f2py; print(numpy.f2py.get_include())"
+  OUTPUT_VARIABLE F2PY_INCLUDE_DIR
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
+# Prepping the module
+set(f2py_module_name "fibby")
+set(fortran_src_file "${CMAKE_SOURCE_DIR}/fib1.f")
+set(f2py_module_c "${f2py_module_name}module.c")
+
+# Target for enforcing dependencies
+add_custom_target(genpyf
+  DEPENDS "${fortran_src_file}"
+)
+add_custom_command(
+  OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${f2py_module_c}"
+  COMMAND ${PYTHON_EXECUTABLE}  -m "numpy.f2py"
+                   "${fortran_src_file}"
+                   -m "fibby"
+                   --lower # Important
+  DEPENDS fib1.f # Fortran source
+)
+
+add_library(${CMAKE_PROJECT_NAME} MODULE
+            "${f2py_module_name}module.c"
+            "${F2PY_INCLUDE_DIR}/fortranobject.c"
+            "${fortran_src_file}")
+
+target_include_directories(${CMAKE_PROJECT_NAME} PUBLIC
+                           ${F2PY_INCLUDE_DIR}
+                           ${NumPy_INCLUDE_DIRS}
+                           ${PYTHON_INCLUDE_DIRS})
+set_target_properties(${CMAKE_PROJECT_NAME} PROPERTIES SUFFIX "${PYTHON_EXTENSION_MODULE_SUFFIX}")
+set_target_properties(${CMAKE_PROJECT_NAME} PROPERTIES PREFIX "")
+
+# Linker fixes
+if (UNIX)
+  if (APPLE)
+    set_target_properties(${CMAKE_PROJECT_NAME} PROPERTIES
+    LINK_FLAGS  '-Wl,-dylib,-undefined,dynamic_lookup')
+  else()
+    set_target_properties(${CMAKE_PROJECT_NAME} PROPERTIES
+  LINK_FLAGS  '-Wl,--allow-shlib-undefined')
+  endif()
+endif()
+
+add_dependencies(${CMAKE_PROJECT_NAME} genpyf)
+
+install(TARGETS ${CMAKE_PROJECT_NAME} DESTINATION fibby)
diff --git a/doc/source/f2py/code/allocarr.f90 b/doc/source/f2py/code/allocarr.f90
new file mode 100644
index 000000000..e0d6c2ec8
--- /dev/null
+++ b/doc/source/f2py/code/allocarr.f90
@@ -0,0 +1,16 @@
+module mod
+  real, allocatable, dimension(:,:) :: b 
+contains
+  subroutine foo
+    integer k
+    if (allocated(b)) then
+       print*, "b=["
+       do k = 1,size(b,1)
+          print*, b(k,1:size(b,2))
+       enddo
+       print*, "]"
+    else
+       print*, "b is not allocated"
+    endif
+  end subroutine foo
+end module mod
diff --git a/doc/source/f2py/code/array.f b/doc/source/f2py/code/array.f
new file mode 100644
index 000000000..ef20c9c20
--- /dev/null
+++ b/doc/source/f2py/code/array.f
@@ -0,0 +1,17 @@
+C FILE: ARRAY.F
+      SUBROUTINE FOO(A,N,M)
+C
+C     INCREMENT THE FIRST ROW AND DECREMENT THE FIRST COLUMN OF A
+C
+      INTEGER N,M,I,J
+      REAL*8 A(N,M)
+Cf2py intent(in,out,copy) a
+Cf2py integer intent(hide),depend(a) :: n=shape(a,0), m=shape(a,1)
+      DO J=1,M
+         A(1,J) = A(1,J) + 1D0
+      ENDDO
+      DO I=1,N
+         A(I,1) = A(I,1) - 1D0
+      ENDDO
+      END
+C END OF FILE ARRAY.F
diff --git a/doc/source/f2py/code/calculate.f b/doc/source/f2py/code/calculate.f
new file mode 100644
index 000000000..4ff570d28
--- /dev/null
+++ b/doc/source/f2py/code/calculate.f
@@ -0,0 +1,14 @@
+      subroutine calculate(x,n)
+cf2py intent(callback) func
+      external func
+c     The following lines define the signature of func for F2PY:
+cf2py real*8 y
+cf2py y = func(y)
+c
+cf2py intent(in,out,copy) x
+      integer n,i
+      real*8 x(n), func
+      do i=1,n
+         x(i) = func(x(i))
+      end do
+      end
diff --git a/doc/source/f2py/code/callback.f b/doc/source/f2py/code/callback.f
new file mode 100644
index 000000000..d5cfc7574
--- /dev/null
+++ b/doc/source/f2py/code/callback.f
@@ -0,0 +1,12 @@
+C FILE: CALLBACK.F
+      SUBROUTINE FOO(FUN,R)
+      EXTERNAL FUN
+      INTEGER I
+      REAL*8 R, FUN
+Cf2py intent(out) r
+      R = 0D0
+      DO I=-5,5
+         R = R + FUN(I)
+      ENDDO
+      END
+C END OF FILE CALLBACK.F
diff --git a/doc/source/f2py/code/callback2.pyf b/doc/source/f2py/code/callback2.pyf
new file mode 100644
index 000000000..3d77eed24
--- /dev/null
+++ b/doc/source/f2py/code/callback2.pyf
@@ -0,0 +1,19 @@
+!    -*- f90 -*-
+python module __user__routines 
+    interface
+        function fun(i) result (r)
+            integer :: i
+            real*8 :: r
+        end function fun
+    end interface
+end python module __user__routines
+
+python module callback2
+    interface
+        subroutine foo(f,r)
+            use __user__routines, f=>fun
+            external f
+            real*8 intent(out) :: r
+        end subroutine foo
+    end interface 
+end python module callback2
diff --git a/doc/source/f2py/code/common.f b/doc/source/f2py/code/common.f
new file mode 100644
index 000000000..b098ab20c
--- /dev/null
+++ b/doc/source/f2py/code/common.f
@@ -0,0 +1,13 @@
+C FILE: COMMON.F
+      SUBROUTINE FOO
+      INTEGER I,X
+      REAL A
+      COMMON /DATA/ I,X(4),A(2,3)
+      PRINT*, "I=",I
+      PRINT*, "X=[",X,"]"
+      PRINT*, "A=["
+      PRINT*, "[",A(1,1),",",A(1,2),",",A(1,3),"]"
+      PRINT*, "[",A(2,1),",",A(2,2),",",A(2,3),"]"
+      PRINT*, "]"
+      END
+C END OF COMMON.F
diff --git a/doc/source/f2py/code/extcallback.f b/doc/source/f2py/code/extcallback.f
new file mode 100644
index 000000000..9a800628e
--- /dev/null
+++ b/doc/source/f2py/code/extcallback.f
@@ -0,0 +1,14 @@
+      subroutine f1()
+         print *, "in f1, calling f2 twice.."
+         call f2()
+         call f2()
+         return
+      end
+      
+      subroutine f2()
+cf2py    intent(callback, hide) fpy
+         external fpy
+         print *, "in f2, calling f2py.."
+         call fpy()
+         return
+      end
diff --git a/doc/source/f2py/code/fib1.f b/doc/source/f2py/code/fib1.f
new file mode 100644
index 000000000..cfbb1eea0
--- /dev/null
+++ b/doc/source/f2py/code/fib1.f
@@ -0,0 +1,18 @@
+C FILE: FIB1.F
+      SUBROUTINE FIB(A,N)
+C
+C     CALCULATE FIRST N FIBONACCI NUMBERS
+C
+      INTEGER N
+      REAL*8 A(N)
+      DO I=1,N
+         IF (I.EQ.1) THEN
+            A(I) = 0.0D0
+         ELSEIF (I.EQ.2) THEN
+            A(I) = 1.0D0
+         ELSE 
+            A(I) = A(I-1) + A(I-2)
+         ENDIF
+      ENDDO
+      END
+C END FILE FIB1.F
diff --git a/doc/source/f2py/code/fib1.pyf b/doc/source/f2py/code/fib1.pyf
new file mode 100644
index 000000000..3d6cc0a54
--- /dev/null
+++ b/doc/source/f2py/code/fib1.pyf
@@ -0,0 +1,12 @@
+!    -*- f90 -*-
+python module fib2 ! in 
+    interface  ! in :fib2
+        subroutine fib(a,n) ! in :fib2:fib1.f
+            real*8 dimension(n) :: a
+            integer optional,check(len(a)>=n),depend(a) :: n=len(a)
+        end subroutine fib
+    end interface 
+end python module fib2
+
+! This file was auto-generated with f2py (version:2.28.198-1366).
+! See http://cens.ioc.ee/projects/f2py2e/
diff --git a/doc/source/f2py/code/fib2.pyf b/doc/source/f2py/code/fib2.pyf
new file mode 100644
index 000000000..4a5ae29f1
--- /dev/null
+++ b/doc/source/f2py/code/fib2.pyf
@@ -0,0 +1,9 @@
+!    -*- f90 -*-
+python module fib2 
+    interface
+        subroutine fib(a,n)
+            real*8 dimension(n),intent(out),depend(n) :: a
+            integer intent(in) :: n
+        end subroutine fib
+    end interface 
+end python module fib2
diff --git a/doc/source/f2py/code/fib3.f b/doc/source/f2py/code/fib3.f
new file mode 100644
index 000000000..08b050cd2
--- /dev/null
+++ b/doc/source/f2py/code/fib3.f
@@ -0,0 +1,21 @@
+C FILE: FIB3.F
+      SUBROUTINE FIB(A,N)
+C
+C     CALCULATE FIRST N FIBONACCI NUMBERS
+C
+      INTEGER N
+      REAL*8 A(N)
+Cf2py intent(in) n
+Cf2py intent(out) a
+Cf2py depend(n) a
+      DO I=1,N
+         IF (I.EQ.1) THEN
+            A(I) = 0.0D0
+         ELSEIF (I.EQ.2) THEN
+            A(I) = 1.0D0
+         ELSE 
+            A(I) = A(I-1) + A(I-2)
+         ENDIF
+      ENDDO
+      END
+C END FILE FIB3.F
diff --git a/doc/source/f2py/code/ftype.f b/doc/source/f2py/code/ftype.f
new file mode 100644
index 000000000..cabbb9e2d
--- /dev/null
+++ b/doc/source/f2py/code/ftype.f
@@ -0,0 +1,9 @@
+C FILE: FTYPE.F
+      SUBROUTINE FOO(N)
+      INTEGER N
+Cf2py integer optional,intent(in) :: n = 13
+      REAL A,X
+      COMMON /DATA/ A,X(3)
+      PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]"
+      END
+C END OF FTYPE.F
diff --git a/doc/source/f2py/code/meson.build b/doc/source/f2py/code/meson.build
new file mode 100644
index 000000000..b756abf8f
--- /dev/null
+++ b/doc/source/f2py/code/meson.build
@@ -0,0 +1,38 @@
+project('f2py_examples', 'c',
+  version : '0.1',
+  default_options : ['warning_level=2'])
+
+add_languages('fortran')
+
+py_mod = import('python')
+py3 = py_mod.find_installation('python3')
+py3_dep = py3.dependency()
+message(py3.path())
+message(py3.get_install_dir())
+
+incdir_numpy = run_command(py3,
+  ['-c', 'import os; os.chdir(".."); import numpy; print(numpy.get_include())'],
+  check : true
+).stdout().strip()
+
+incdir_f2py = run_command(py3,
+    ['-c', 'import os; os.chdir(".."); import numpy.f2py; print(numpy.f2py.get_include())'],
+    check : true
+).stdout().strip()
+
+fibby_source = custom_target('fibbymodule.c',
+                            input : ['fib1.f'],
+                            output : ['fibbymodule.c'],
+                            command : [ py3, '-m', 'numpy.f2py', '@INPUT@',
+                            '-m', 'fibby', '--lower' ]
+                            )
+
+inc_np = include_directories(incdir_numpy, incdir_f2py)
+
+py3.extension_module('fibby',
+           'fib1.f',
+           fibby_source,
+           incdir_f2py+'/fortranobject.c',
+           include_directories: inc_np,
+           dependencies : py3_dep,
+           install : true)
diff --git a/doc/source/f2py/code/meson_upd.build b/doc/source/f2py/code/meson_upd.build
new file mode 100644
index 000000000..97bd8d175
--- /dev/null
+++ b/doc/source/f2py/code/meson_upd.build
@@ -0,0 +1,37 @@
+project('f2py_examples', 'c',
+  version : '0.1',
+  default_options : ['warning_level=2'])
+
+add_languages('fortran')
+
+py_mod = import('python')
+py3 = py_mod.find_installation('python3')
+py3_dep = py3.dependency()
+message(py3.path())
+message(py3.get_install_dir())
+
+incdir_numpy = run_command(py3,
+  ['-c', 'import os; os.chdir(".."); import numpy; print(numpy.get_include())'],
+  check : true
+).stdout().strip()
+
+incdir_f2py = run_command(py3,
+    ['-c', 'import os; os.chdir(".."); import numpy.f2py; print(numpy.f2py.get_include())'],
+    check : true
+).stdout().strip()
+
+fibby_source = custom_target('fibbymodule.c',
+                            input : ['fib1.f'],
+                            output : ['fibbymodule.c'],
+                            command : [ py3, '-m', 'numpy.f2py', '@INPUT@',
+                            '-m', 'fibby', '--lower' ])
+
+inc_np = include_directories(incdir_numpy, incdir_f2py)
+
+py3.extension_module('fibby',
+           'fib1.f',
+           fibby_source,
+           incdir_f2py+'/fortranobject.c',
+           include_directories: inc_np,
+           dependencies : py3_dep,
+           install : true)
diff --git a/doc/source/f2py/code/moddata.f90 b/doc/source/f2py/code/moddata.f90
new file mode 100644
index 000000000..0e98f0467
--- /dev/null
+++ b/doc/source/f2py/code/moddata.f90
@@ -0,0 +1,18 @@
+module mod
+  integer i
+  integer :: x(4)
+  real, dimension(2,3) :: a
+  real, allocatable, dimension(:,:) :: b 
+contains
+  subroutine foo
+    integer k
+    print*, "i=",i
+    print*, "x=[",x,"]"
+    print*, "a=["
+    print*, "[",a(1,1),",",a(1,2),",",a(1,3),"]"
+    print*, "[",a(2,1),",",a(2,2),",",a(2,3),"]"
+    print*, "]"
+    print*, "Setting a(1,2)=a(1,2)+3"
+    a(1,2) = a(1,2)+3
+  end subroutine foo
+end module mod
diff --git a/doc/source/f2py/code/pyproj_skbuild.toml b/doc/source/f2py/code/pyproj_skbuild.toml
new file mode 100644
index 000000000..bcd6ae99c
--- /dev/null
+++ b/doc/source/f2py/code/pyproj_skbuild.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel", "scikit-build", "cmake>=3.9", "numpy>=1.21"]
+build-backend = "setuptools.build_meta"
diff --git a/doc/source/f2py/code/results/allocarr_session.dat b/doc/source/f2py/code/results/allocarr_session.dat
new file mode 100644
index 000000000..ba168c22a
--- /dev/null
+++ b/doc/source/f2py/code/results/allocarr_session.dat
@@ -0,0 +1,32 @@
+>>> import allocarr
+>>> print(allocarr.mod.__doc__)
+b : 'f'-array(-1,-1), not allocated
+foo()
+
+Wrapper for ``foo``.
+
+
+
+>>> allocarr.mod.foo()  
+ b is not allocated
+>>> allocarr.mod.b = [[1, 2, 3], [4, 5, 6]]             # allocate/initialize b
+>>> allocarr.mod.foo()
+ b=[
+   1.000000       2.000000       3.000000    
+   4.000000       5.000000       6.000000    
+ ]
+>>> allocarr.mod.b                                      # b is Fortran-contiguous
+array([[ 1.,  2.,  3.],
+       [ 4.,  5.,  6.]], dtype=float32)
+>>> allocarr.mod.b.flags.f_contiguous
+True
+>>> allocarr.mod.b = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]  # reallocate/initialize b
+>>> allocarr.mod.foo()
+ b=[
+   1.000000       2.000000       3.000000    
+   4.000000       5.000000       6.000000    
+   7.000000       8.000000       9.000000    
+ ]
+>>> allocarr.mod.b = None                               # deallocate array
+>>> allocarr.mod.foo()
+ b is not allocated
diff --git a/doc/source/f2py/code/results/array_session.dat b/doc/source/f2py/code/results/array_session.dat
new file mode 100644
index 000000000..714c03651
--- /dev/null
+++ b/doc/source/f2py/code/results/array_session.dat
@@ -0,0 +1,87 @@
+>>> import arr
+>>> from numpy import asfortranarray
+>>> print(arr.foo.__doc__)
+a = foo(a,[overwrite_a])
+
+Wrapper for ``foo``.
+
+Parameters
+----------
+a : input rank-2 array('d') with bounds (n,m)
+
+Other Parameters
+----------------
+overwrite_a : input int, optional
+    Default: 0
+
+Returns
+-------
+a : rank-2 array('d') with bounds (n,m)
+
+>>> a = arr.foo([[1, 2, 3],
+...              [4, 5, 6]])
+created an array from object
+>>> print(a)
+[[ 1.  3.  4.]
+ [ 3.  5.  6.]]
+>>> a.flags.c_contiguous
+False
+>>> a.flags.f_contiguous
+True
+# even if a is proper-contiguous and has proper type,
+# a copy is made forced by intent(copy) attribute
+# to preserve its original contents
+>>> b = arr.foo(a)
+copied an array: size=6, elsize=8
+>>> print(a)
+[[ 1.  3.  4.]
+ [ 3.  5.  6.]]
+>>> print(b)
+[[ 1.  4.  5.]
+ [ 2.  5.  6.]]
+>>> b = arr.foo(a, overwrite_a = 1) # a is passed directly to Fortran
+...                                 # routine and its contents is discarded
+... 
+>>> print(a)
+[[ 1.  4.  5.]
+ [ 2.  5.  6.]]
+>>> print(b)
+[[ 1.  4.  5.]
+ [ 2.  5.  6.]]
+>>> a is b                          # a and b are actually the same objects
+True
+>>> print(arr.foo([1, 2, 3]))       # different rank arrays are allowed
+created an array from object
+[ 1.  1.  2.]
+>>> print(arr.foo([[[1], [2], [3]]]))
+created an array from object
+[[[ 1.]
+  [ 1.]
+  [ 2.]]]
+>>>
+>>> # Creating arrays with column major data storage order:
+ ...
+>>> s = asfortranarray([[1, 2, 3], [4, 5, 6]])
+>>> s.flags.f_contiguous
+True
+>>> print(s)
+[[1 2 3]
+ [4 5 6]]
+>>> print(arr.foo(s))
+>>> s2 = asfortranarray(s)
+>>> s2 is s    # an array with column major storage order 
+               # is returned immediately
+True
+>>> # Note that arr.foo returns a column major data storage order array:
+ ...
+>>> s3 = ascontiguousarray(s)
+>>> s3.flags.f_contiguous
+False
+>>> s3.flags.c_contiguous
+True
+>>> s3 = arr.foo(s3)
+copied an array: size=6, elsize=8
+>>> s3.flags.f_contiguous
+True
+>>> s3.flags.c_contiguous
+False
diff --git a/doc/source/f2py/code/results/calculate_session.dat b/doc/source/f2py/code/results/calculate_session.dat
new file mode 100644
index 000000000..c4c380700
--- /dev/null
+++ b/doc/source/f2py/code/results/calculate_session.dat
@@ -0,0 +1,6 @@
+>>> import foo
+>>> foo.calculate(range(5), lambda x: x*x)
+array([  0.,   1.,   4.,   9.,  16.])
+>>> import math
+>>> foo.calculate(range(5), math.exp)
+array([  1.        ,   2.71828183,   7.3890561,  20.08553692,  54.59815003])
diff --git a/doc/source/f2py/code/results/callback_session.dat b/doc/source/f2py/code/results/callback_session.dat
new file mode 100644
index 000000000..460c9ce28
--- /dev/null
+++ b/doc/source/f2py/code/results/callback_session.dat
@@ -0,0 +1,35 @@
+>>> import callback
+>>> print(callback.foo.__doc__)
+r = foo(fun,[fun_extra_args])
+
+Wrapper for ``foo``.
+
+Parameters
+----------
+fun : call-back function
+
+Other Parameters
+----------------
+fun_extra_args : input tuple, optional
+    Default: ()
+
+Returns
+-------
+r : float
+
+Notes
+-----
+Call-back functions::
+
+  def fun(i): return r
+  Required arguments:
+    i : input int
+  Return objects:
+    r : float
+
+>>> def f(i): return i*i
+... 
+>>> print(callback.foo(f))
+110.0
+>>> print(callback.foo(lambda i:1))
+11.0
diff --git a/doc/source/f2py/code/results/common_session.dat b/doc/source/f2py/code/results/common_session.dat
new file mode 100644
index 000000000..2595bfbd5
--- /dev/null
+++ b/doc/source/f2py/code/results/common_session.dat
@@ -0,0 +1,30 @@
+>>> import common
+>>> print(common.data.__doc__)
+i : 'i'-scalar
+x : 'i'-array(4)
+a : 'f'-array(2,3)
+
+>>> common.data.i = 5
+>>> common.data.x[1] = 2 
+>>> common.data.a = [[1,2,3],[4,5,6]]
+>>> common.foo()
+>>> common.foo()
+ I=           5
+ X=[           0           2           0           0 ]
+ A=[
+ [   1.00000000     ,   2.00000000     ,   3.00000000     ]
+ [   4.00000000     ,   5.00000000     ,   6.00000000     ]
+ ]
+>>> common.data.a[1] = 45
+>>> common.foo()
+ I=           5
+ X=[           0           2           0           0 ]
+ A=[
+ [   1.00000000     ,   2.00000000     ,   3.00000000     ]
+ [   45.0000000     ,   45.0000000     ,   45.0000000     ]
+ ]
+>>> common.data.a                 # a is Fortran-contiguous
+array([[  1.,   2.,   3.],
+       [ 45.,  45.,  45.]], dtype=float32)
+>>> common.data.a.flags.f_contiguous
+True
\ No newline at end of file
diff --git a/doc/source/f2py/code/results/compile_session.dat b/doc/source/f2py/code/results/compile_session.dat
new file mode 100644
index 000000000..5c42742be
--- /dev/null
+++ b/doc/source/f2py/code/results/compile_session.dat
@@ -0,0 +1,11 @@
+>>> import numpy.f2py
+>>> fsource = '''
+...       subroutine foo
+...       print*, "Hello world!"
+...       end 
+... '''
+>>> numpy.f2py.compile(fsource, modulename='hello', verbose=0)
+0
+>>> import hello
+>>> hello.foo()
+ Hello world!
diff --git a/doc/source/f2py/code/results/extcallback_session.dat b/doc/source/f2py/code/results/extcallback_session.dat
new file mode 100644
index 000000000..5b97ab7cf
--- /dev/null
+++ b/doc/source/f2py/code/results/extcallback_session.dat
@@ -0,0 +1,19 @@
+>>> import pfromf
+>>> pfromf.f2()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+pfromf.error: Callback fpy not defined (as an argument or module pfromf attribute).
+
+>>> def f(): print("python f")
+... 
+>>> pfromf.fpy = f
+>>> pfromf.f2()
+ in f2, calling f2py..
+python f
+>>> pfromf.f1()
+ in f1, calling f2 twice..
+ in f2, calling f2py..
+python f
+ in f2, calling f2py..
+python f
+>>> 
\ No newline at end of file
diff --git a/doc/source/f2py/code/results/ftype_session.dat b/doc/source/f2py/code/results/ftype_session.dat
new file mode 100644
index 000000000..e39cc128d
--- /dev/null
+++ b/doc/source/f2py/code/results/ftype_session.dat
@@ -0,0 +1,21 @@
+>>> import ftype
+>>> print(ftype.__doc__)
+This module 'ftype' is auto-generated with f2py (version:2).
+Functions:
+  foo(n=13)
+COMMON blocks:
+  /data/ a,x(3)
+.
+>>> type(ftype.foo), type(ftype.data)
+(<class 'fortran'>, <class 'fortran'>)
+>>> ftype.foo()
+ IN FOO: N= 13 A=  0. X=[  0.  0.  0.]
+>>> ftype.data.a = 3
+>>> ftype.data.x = [1,2,3]
+>>> ftype.foo()
+ IN FOO: N= 13 A=  3. X=[  1.  2.  3.]
+>>> ftype.data.x[1] = 45  
+>>> ftype.foo(24)
+ IN FOO: N= 24 A=  3. X=[  1.  45.  3.]
+>>> ftype.data.x
+array([  1.,  45.,   3.], dtype=float32)
diff --git a/doc/source/f2py/code/results/moddata_session.dat b/doc/source/f2py/code/results/moddata_session.dat
new file mode 100644
index 000000000..824bd86fc
--- /dev/null
+++ b/doc/source/f2py/code/results/moddata_session.dat
@@ -0,0 +1,28 @@
+>>> import moddata
+>>> print(moddata.mod.__doc__)
+i : 'i'-scalar
+x : 'i'-array(4)
+a : 'f'-array(2,3)
+b : 'f'-array(-1,-1), not allocated
+foo()
+
+Wrapper for ``foo``.
+
+
+
+>>> moddata.mod.i = 5  
+>>> moddata.mod.x[:2] = [1,2]
+>>> moddata.mod.a = [[1,2,3],[4,5,6]]
+>>> moddata.mod.foo()                
+ i=           5
+ x=[           1           2           0           0 ]
+ a=[
+ [   1.000000     ,   2.000000     ,   3.000000     ]
+ [   4.000000     ,   5.000000     ,   6.000000     ]
+ ]
+ Setting a(1,2)=a(1,2)+3
+>>> moddata.mod.a               # a is Fortran-contiguous
+array([[ 1.,  5.,  3.],
+       [ 4.,  5.,  6.]], dtype=float32)
+>>> moddata.mod.a.flags.f_contiguous
+True
diff --git a/doc/source/f2py/code/results/run_main_session.dat b/doc/source/f2py/code/results/run_main_session.dat
new file mode 100644
index 000000000..be6cacd22
--- /dev/null
+++ b/doc/source/f2py/code/results/run_main_session.dat
@@ -0,0 +1,14 @@
+>>> import numpy.f2py
+>>> r = numpy.f2py.run_main(['-m','scalar','doc/source/f2py/scalar.f'])
+Reading fortran codes...
+        Reading file 'doc/source/f2py/scalar.f' (format:fix,strict)
+Post-processing...
+        Block: scalar
+                        Block: FOO
+Building modules...
+        Building module "scalar"...
+        Wrote C/API module "scalar" to file "./scalarmodule.c"
+>>> print(r)
+{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py/src/fortranobject.h'],
+	 'csrc': ['./scalarmodule.c', 
+                  '/home/users/pearu/src_cvs/f2py/src/fortranobject.c']}}
diff --git a/doc/source/f2py/code/results/scalar_session.dat b/doc/source/f2py/code/results/scalar_session.dat
new file mode 100644
index 000000000..3bb45ed68
--- /dev/null
+++ b/doc/source/f2py/code/results/scalar_session.dat
@@ -0,0 +1,24 @@
+>>> import scalar
+>>> print(scalar.foo.__doc__)
+foo(a,b)
+
+Wrapper for ``foo``.
+
+Parameters
+----------
+a : input float
+b : in/output rank-0 array(float,'d')
+ 
+>>> scalar.foo(2, 3)   
+     A=  2. B=  3.
+ INCREMENT A AND B
+ NEW A=  3. B=  4.
+>>> import numpy
+>>> a = numpy.array(2)   # these are integer rank-0 arrays
+>>> b = numpy.array(3)
+>>> scalar.foo(a, b)
+     A=  2. B=  3.
+ INCREMENT A AND B
+ NEW A=  3. B=  4.
+>>> print(a, b)          # note that only b is changed in situ
+2 4
diff --git a/doc/source/f2py/code/results/spam_session.dat b/doc/source/f2py/code/results/spam_session.dat
new file mode 100644
index 000000000..bd5832d88
--- /dev/null
+++ b/doc/source/f2py/code/results/spam_session.dat
@@ -0,0 +1,5 @@
+>>> import spam
+>>> status = spam.system('whoami')
+pearu
+>>> status = spam.system('blah')
+sh: line 1: blah: command not found
\ No newline at end of file
diff --git a/doc/source/f2py/code/results/string_session.dat b/doc/source/f2py/code/results/string_session.dat
new file mode 100644
index 000000000..e8f7854d9
--- /dev/null
+++ b/doc/source/f2py/code/results/string_session.dat
@@ -0,0 +1,30 @@
+>>> import mystring
+>>> print(mystring.foo.__doc__)
+foo(a,b,c,d)
+
+Wrapper for ``foo``.
+
+Parameters
+----------
+a : input string(len=5)
+b : in/output rank-0 array(string(len=5),'c')
+c : input string(len=-1)
+d : in/output rank-0 array(string(len=-1),'c')
+
+>>> from numpy import array
+>>> a = array(b'123\0\0')
+>>> b = array(b'123\0\0')
+>>> c = array(b'123')
+>>> d = array(b'123')
+>>> mystring.foo(a, b, c, d)
+ A=123
+ B=123
+ C=123
+ D=123
+ CHANGE A,B,C,D
+ A=A23
+ B=B23
+ C=C23
+ D=D23
+>>> a[()], b[()], c[()], d[()]
+(b'123', b'B23', b'123', b'D2')
diff --git a/doc/source/f2py/code/results/var_session.dat b/doc/source/f2py/code/results/var_session.dat
new file mode 100644
index 000000000..fb0f798bf
--- /dev/null
+++ b/doc/source/f2py/code/results/var_session.dat
@@ -0,0 +1,3 @@
+>>> import var
+>>> var.BAR
+5
\ No newline at end of file
diff --git a/doc/source/f2py/code/scalar.f b/doc/source/f2py/code/scalar.f
new file mode 100644
index 000000000..c22f639ed
--- /dev/null
+++ b/doc/source/f2py/code/scalar.f
@@ -0,0 +1,12 @@
+C FILE: SCALAR.F
+      SUBROUTINE FOO(A,B)
+      REAL*8 A, B
+Cf2py intent(in) a
+Cf2py intent(inout) b
+      PRINT*, "    A=",A," B=",B
+      PRINT*, "INCREMENT A AND B"
+      A = A + 1D0
+      B = B + 1D0
+      PRINT*, "NEW A=",A," B=",B
+      END
+C END OF FILE SCALAR.F
diff --git a/doc/source/f2py/code/setup_example.py b/doc/source/f2py/code/setup_example.py
new file mode 100644
index 000000000..479acc004
--- /dev/null
+++ b/doc/source/f2py/code/setup_example.py
@@ -0,0 +1,16 @@
+from numpy.distutils.core import Extension
+
+ext1 = Extension(name = 'scalar',
+                 sources = ['scalar.f'])
+ext2 = Extension(name = 'fib2',
+                 sources = ['fib2.pyf', 'fib1.f'])
+
+if __name__ == "__main__":
+    from numpy.distutils.core import setup
+    setup(name = 'f2py_example',
+          description       = "F2PY Users Guide examples",
+          author            = "Pearu Peterson",
+          author_email      = "pearu@cens.ioc.ee",
+          ext_modules = [ext1, ext2]
+          )
+# End of setup_example.py
diff --git a/doc/source/f2py/code/setup_skbuild.py b/doc/source/f2py/code/setup_skbuild.py
new file mode 100644
index 000000000..28dcdcb1f
--- /dev/null
+++ b/doc/source/f2py/code/setup_skbuild.py
@@ -0,0 +1,10 @@
+from skbuild import setup
+
+setup(
+    name="fibby",
+    version="0.0.1",
+    description="a minimal example package (fortran version)",
+    license="MIT",
+    packages=['fibby'],
+    python_requires=">=3.7",
+)
diff --git a/doc/source/f2py/code/spam.pyf b/doc/source/f2py/code/spam.pyf
new file mode 100644
index 000000000..21ea18b77
--- /dev/null
+++ b/doc/source/f2py/code/spam.pyf
@@ -0,0 +1,19 @@
+!    -*- f90 -*-
+python module spam
+    usercode '''
+  static char doc_spam_system[] = "Execute a shell command.";
+  static PyObject *spam_system(PyObject *self, PyObject *args)
+  {
+    char *command;
+    int sts;
+
+    if (!PyArg_ParseTuple(args, "s", &command))
+        return NULL;
+    sts = system(command);
+    return Py_BuildValue("i", sts);
+  }
+    '''
+    pymethoddef '''
+    {"system",  spam_system, METH_VARARGS, doc_spam_system},
+    '''
+end python module spam
diff --git a/doc/source/f2py/code/string.f b/doc/source/f2py/code/string.f
new file mode 100644
index 000000000..9246f02e7
--- /dev/null
+++ b/doc/source/f2py/code/string.f
@@ -0,0 +1,21 @@
+C FILE: STRING.F
+      SUBROUTINE FOO(A,B,C,D)
+      CHARACTER*5 A, B
+      CHARACTER*(*) C,D
+Cf2py intent(in) a,c
+Cf2py intent(inout) b,d
+      PRINT*, "A=",A
+      PRINT*, "B=",B
+      PRINT*, "C=",C
+      PRINT*, "D=",D
+      PRINT*, "CHANGE A,B,C,D"
+      A(1:1) = 'A'
+      B(1:1) = 'B'
+      C(1:1) = 'C'
+      D(1:1) = 'D'
+      PRINT*, "A=",A
+      PRINT*, "B=",B
+      PRINT*, "C=",C
+      PRINT*, "D=",D
+      END
+C END OF FILE STRING.F
diff --git a/doc/source/f2py/code/var.pyf b/doc/source/f2py/code/var.pyf
new file mode 100644
index 000000000..8275ff3af
--- /dev/null
+++ b/doc/source/f2py/code/var.pyf
@@ -0,0 +1,11 @@
+!    -*- f90 -*-
+python module var
+  usercode '''
+    int BAR = 5;
+  '''
+  interface
+    usercode '''
+      PyDict_SetItemString(d,"BAR",PyInt_FromLong(BAR));
+    '''
+  end interface
+end python module