V4

CHANGELOG.md

@@ -1,6 +1,6 @@
 # CHANGELOG of Wannier90
 
-## v4.0.0 (10 July 2026)
+## v4.0.0 (27 July 2026)
 
 ### New features
 
@@ -20,7 +20,7 @@
 
 - Update to the CODATA standard version [[#649]](https://github.com/wannier-developers/wannier90/pull/649)
 
-- Significant code refactoring for data encapsulation, error handling, etc
+- Significant code refactoring for data encapsulation, error handling, etc.
 
 
 ## v3.1.0 (5th March 2020)

docs/docs/user_guide/wannier90/library_mode.md

@@ -53,7 +53,7 @@ the library in serial and parallel.  These examples are distributed in the
 directory `test-suite/library-mode-test`.
 
 Section [C-interface](#c-interface) lists the C interface functions and shows
-how to use them.
+how to use them.  A test is available in `test-suite/library-mode-test-C-interface`.
 
 $M_{mn}^{(\mathbf{k,b})}$ overlaps (Ref. [@marzari-prb97], Eq. (25)) and
 $A_{mn}^{(\mathbf{k})}=\left\langle \psi_{m\mathbf{k}}|g_{n}\right\rangle$
@@ -68,12 +68,12 @@ projections (Ref. [@marzari-prb97], Eq. (62); Ref. [@souza-prb01], Eq. (22))
 - the `distk` array communicates to Wannier90 how k-points are distributed over
 MPI ranks.  In particular this affects the decomposition of the $M$-matrix.
 
-- `total_bands` is provided for convenience when working with `excluded_bands`
+- `total_bands` is provided for convenience when working with `exclude_bands`
 when these determine the number of bands in the Wannier90 calculation instead
 of vice-versa.
 
 - `dump_inputs` writes a minimal .win file and .mmn, .amn and .eig files for
-use by standalone executable
+use by standalone executable.
 
 ## Using the Library
 
@@ -84,7 +84,7 @@ use by standalone executable
                           w90_get_gkpb, w90_get_proj, w90_get_centres, &
                           w90_get_spreads, w90_plot, w90_set_eigval, &
                           w90_set_u_opt, w90_set_m_local, w90_set_u_matrix, &
-                          w90_input_reader, input_print_details
+                          w90_input_reader, w90_transport
 ```
 
 The library exposes a number of functions via a Fortran module that should be
@@ -104,17 +104,20 @@ The library exposes a number of functions via a Fortran module that should be
    [w90_get_nnkp](#w90_get_nnkp)
 8. obtain the finite difference neighbour BZ offsets using
    [w90_get_gkpb](#w90_get_gkpb)
-9. (optionally) get projector definition corresponding to input string
-   [w90_get_proj](#w90_get_proj)
-10. calculate projections and overlap
+9. get projector definition corresponding to input string
+   [w90_get_proj](#w90_get_proj)  (your code may have its own mechanism for
+choosing projectors; this is a convenience function that uses Wannier90 to
+parse the .win projector string into a site,l,m,zaxis configuration)
+10. calculate projections and overlap matrices
 11. pass pointers to $U$, $M$, $U^{opt}$ and (if disentangling) eigenvalue
     matrices using [w90_set_eigval](#w90_set_eigval),
 [w90_set_u_matrix](#w90_set_u_matrix), etc
 12. initial projections, $A$, should be stored in the $U^{opt}$ matrix
 13. if disentangling is required, call [w90_disentangle](#w90_disentangle)
 14. prepare for MLWF algorithm by projecting $M$, $U^{opt}$ onto subspace by
     calling [w90_project_overlap](#w90_project_overlap)
-15. call [w90_wannierise](#w90_wannierise)
+15. call [w90_wannierise](#w90_wannierise) (this may be called multiple times
+    in order to test convergence)
 16. obtain centres and spreads with [w90_get_centres](#w90_get_centres) and
     [w90_get_spreads](#w90_get_spreads)
 
@@ -350,7 +353,7 @@ Must follow w90_input_setopt
 Probe library for position of WF spreads.
 
 On entry, spreads must be a double precision array allocated with
-dimension(3,num_wannier)
+dimension(num_wannier).
 
 Must follow w90_input_setopt
 
@@ -377,6 +380,22 @@ value.  Successful optimisation returns ierr zero.
     type(lib_common_type), intent(inout) :: common_data
 ```
 
+### w90_transport
+
+Perform those transport property calculations that are implemented in the
+Wannier90 main executable (note that this is a much smaller functionality than
+that afforded by postw90.x).  Arguments are the Wannier90 library object,
+integer Fortran unit numbers for standard error and output streams and an
+integer status value.  Successful optimisation returns ierr zero.
+
+```fortran title="Fortran"
+  subroutine w90_transport(common_data, istdout, istderr, ierr)
+
+    integer, intent(in) :: istdout, istderr
+    integer, intent(out) :: ierr
+    type(lib_common_type), intent(inout) :: common_data
+```
+
 ### w90_set_eigval
 
 Pass a pointer to a preexisting double precision array of dimension(nbands,
@@ -405,37 +424,36 @@ This must be accomplished before calling w90_disentangle.
 This must follow w90_input_setopt.
 
 ```fortran title="Fortran"
-  subroutine w90_set_u_opt(common_data, u_opt)
+  subroutine w90_set_u_opt(common_data, u_matrix_opt)
 
     type(lib_common_type), intent(inout) :: common_data
-    complex(kind=dp), intent(inout), target :: u_opt(:, :, :)
+    complex(kind=dp), intent(inout), target :: u_matrix_opt(:, :, :)
 ```
 
 ### w90_set_m_local
 
 Pass a pointer to a preexisting double precision complex array of
-dimension(nbands, nbands, num_wannier, nklocal), where nklocal is the number of
-kpoints associated with this rank.  In serial, nklocal equals num_kpoints.
-The distribution of M across k-points is described by the `distk` array.
+dimension(nbands, nbands, nn, nklocal), where nklocal is the number of kpoints
+associated with this rank and nn is the number of finite difference k-point
+neighbours.  In serial, nklocal equals num_kpoints.  The distribution of M
+across k-points is described by the `distk` array.
 
-This must be accomplished before calling w90_disentangle or w90_wannierise.
-
-This must follow w90_input_setopt.
+This must be done before calling w90_disentangle or w90_wannierise and must
+follow w90_input_setopt.
 
 ```fortran title="Fortran"
-  subroutine w90_set_m_local(common_data, m_orig)
+  subroutine w90_set_m_local(common_data, m_matrix_local)
 
     type(lib_common_type), intent(inout) :: common_data
-    complex(kind=dp), intent(inout), target :: m_orig(:, :, :, :)
+    complex(kind=dp), intent(inout), target :: m_matrix_local(:, :, :, :)
 ```
 
 ### w90_set_u_matrix
 
 Pass a pointer to a preexisting double precision complex array of
-dimension(num_wannier, num_wannier, nklocal), where nklocal is the number of
-kpoints associated with this rank.  In serial, nklocal equals num_kpoints.
+dimension(num_wannier, num_wannier, num_kpoints).
 
-The U matrix is duplicated on all ranks.
+The full U matrix is duplicated on all ranks.
 
 This must be accomplished before calling w90_disentangle or w90_wannierise.
 
@@ -454,7 +472,7 @@ w90_input_reader provides an optional mechanism for passing additional flags to
 the library using the input (.win) file.  All valid input tokens of the main
 program may be specified in this way, except for variables listed in
 [w90_set_option](#w90_set_option), i.e. the most important variables defining the
-calculation must be specified by w90_set_input.
+calculation must be specified by w90_set_option.
 
 w90_input_reader must be called after w90_input_setopt.
 
@@ -509,6 +527,11 @@ must be added to your "include" path.
 
 The library should be compiled with the same compiler as the calling code.
 
+If you link to the parallel library, you must initialise the MPI system
+(mpi_init) and must pass a valid communicator to the library (failure to do
+this results in an error:  "Error: parallel Wannier90 library invoked with
+invalid communicator, exiting.  Use w90_set_comm()!" )
+
 ## Examples
 
 See directory: test-suite/library-mode-test/
@@ -528,13 +551,13 @@ directory test-suite/library-mode-test-C-interface/
 The directory `wrap/` in the sources contains an Python wrapping of the Fortran
 library.  It is constructed using the [f90wrap
 package](https://github.com/jameskermode/f90wrap) (See also DOI
-10.1088/1361-648X/ab82d2).
+10.1088/1361-648X/ab82d2).  Specifiy `F90WRAP` in the build configuration.
 
 ### Build instructions
 
 - Make sure f90wrap is installed
 - cd wrap
-- make -f Makefile.serial or Makefile.mpi
+- make -f Makefile
 
 Edit the makefiles as appropriate.
 
@@ -584,7 +607,8 @@ MPI libraries for Fortran may support both old style ('use mpi') and more
 modern interfaces ('use mpi_f08'); depending on the interface used to build the
 library, communicator objects may be specially typed or treated as integer and
 this must be consistent with what is used in the calling code.  This behaviour
-is driven when Wannier90 is compiled by the use of COMMS=MPI90 or COMMS=MPI08.
+can be adjusted by compiling Wannier90 with use of COMMS=MPI90 , MPI08 or MPIH,
+as needed.
 
 ```bash
 696 | call input_setopt(w90main, filename, stdout, stderr, ierr, comm)

src/c_interface.F90

@@ -57,7 +57,8 @@ subroutine w90_create(w90_obj) bind(c)
     !! return a c-pointer to a instance of the wannier90 library data structure
     type(lib_common_type), pointer :: common_data
     type(w90_data) :: w90_obj
-    if (c_associated(w90_obj%caddr)) return
+    !if (c_associated(w90_obj%caddr)) return ! we can't distinguish an uninitialised pointer (junk) from valid one here; test is reliable.
+    ! -> policy: this function *always* creates a new object
     allocate (common_data)
     w90_obj%caddr = c_loc(common_data)
   end subroutine
@@ -475,15 +476,17 @@ subroutine w90_set_comm_f(w90_obj, comm) bind(c)
     implicit none
 #ifdef MPIH
     include 'mpif.h'
+#endif
+    integer(kind=c_int), intent(in) :: comm
+#ifdef MPI08
+    type(mpi_comm) :: comm08
 #endif
     type(w90_data), intent(in), value :: w90_obj
     type(lib_common_type), pointer :: w90_fptr
-    integer(kind=c_int), intent(in) :: comm
 
     call c_f_pointer(w90_obj%caddr, w90_fptr)
 
 #ifdef MPI08
-    type(mpi_comm) :: comm08
     ! Manually assign the integer to the type's internal handle
     comm08%MPI_VAL = comm
     call w90_set_comm_ff(w90_fptr, comm08)

src/disentangle.F90

@@ -4208,7 +4208,7 @@ subroutine internal_zmatrix_gamma(cbw, m_matrix_orig_local, u_matrix_opt, rmtrx,
     real(kind=dp), intent(in) :: wb(:)
     real(kind=dp), intent(out) :: rmtrx(:, :)
 
-    complex(kind=dp), intent(in) :: cbw(:, :)
+    complex(kind=dp), intent(inout) :: cbw(:, :)
     complex(kind=dp), intent(in) :: m_matrix_orig_local(:, :, :, :)
     complex(kind=dp), intent(inout) :: u_matrix_opt(:, :, :)
 

src/io.F90

@@ -39,7 +39,7 @@ module w90_io
 
   private
 
-  character(len=10), parameter, public :: w90_version = '3.1.0 ' !! Label for this version of wannier90
+  character(len=10), parameter, public :: w90_version = '4.0.0 ' !! Label for this version of wannier90
 
   public :: io_stopwatch_start
   public :: io_stopwatch_stop

src/kmesh.F90

@@ -295,7 +295,6 @@ subroutine kmesh_get(kmesh_input, kmesh_info, print_output, kpt_latt, real_latti
       end if
       write (stdout, '("|")')
     end if
-    !end if
 
     kmesh_info%nntot = 0
     do loop_s = 1, kmesh_input%num_shells
@@ -356,11 +355,11 @@ subroutine kmesh_get(kmesh_input, kmesh_info, print_output, kpt_latt, real_latti
     end if
 
     ! higher-order algorithm: include 2b, 3b, ..., Nb shells, and modify bweights
-    if (kmesh_input%higher_order_nearest_shells .and. print_output%iprint > 0) then
-      write (stdout, '(a)') ' | WARNING: higher_order_nearest_shells is an experimental feature, and has   |', &
+    if (kmesh_input%higher_order_nearest_shells) then
+      if (print_output%iprint > 0) write (stdout, '(a)') &
+        ' | WARNING: higher_order_nearest_shells is an experimental feature, and has   |', &
         ' | not been extensively tested.                                               |'
     else
-      ! update nntot
       kmesh_info%nntot = kmesh_info%nntot*kmesh_input%higher_order_n
     end if
 
@@ -663,7 +662,6 @@ subroutine kmesh_get(kmesh_input, kmesh_info, print_output, kpt_latt, real_latti
       write (stdout, '(1x,"+",76("-"),"+")')
     end if
 
-    !
     kmesh_info%wbtot = 0.0_dp
     nnx = 0
     do ndnnx = 1, kmesh_input%num_shells
@@ -1144,7 +1142,7 @@ subroutine kmesh_dealloc(kmesh_info, error, comm)
     type(w90_comm_type), intent(in) :: comm
     integer :: ierr
 
-    ! Deallocate real arrays that are public
+    ! Deallocate real arrays
     if (allocated(kmesh_info%bk)) then
       deallocate (kmesh_info%bk, stat=ierr)
       if (ierr /= 0) then
@@ -1166,8 +1164,29 @@ subroutine kmesh_dealloc(kmesh_info, error, comm)
         return
       end if
     end if
+    if (allocated(kmesh_info%nnord)) then
+      deallocate (kmesh_info%wb, stat=ierr)
+      if (ierr /= 0) then
+        call set_error_dealloc(error, 'Error in deallocating wb in kmesh_dealloc', comm)
+        return
+      end if
+    end if
+    if (allocated(kmesh_info%nninv)) then
+      deallocate (kmesh_info%wb, stat=ierr)
+      if (ierr /= 0) then
+        call set_error_dealloc(error, 'Error in deallocating wb in kmesh_dealloc', comm)
+        return
+      end if
+    end if
+    if (allocated(kmesh_info%nnrev)) then
+      deallocate (kmesh_info%wb, stat=ierr)
+      if (ierr /= 0) then
+        call set_error_dealloc(error, 'Error in deallocating wb in kmesh_dealloc', comm)
+        return
+      end if
+    end if
 
-    ! Deallocate integer arrays that are public
+    ! Deallocate integer arrays
     if (allocated(kmesh_info%neigh)) then
       deallocate (kmesh_info%neigh, stat=ierr)
       if (ierr /= 0) then

src/library_extra.F90

@@ -74,7 +74,6 @@ module w90_library_extra
   public :: read_chkpt
   public :: read_eigvals
   public :: set_kpoint_distribution
-  public :: set_parallel_comms
   public :: write_chkpt
   public :: write_kmesh
 
@@ -211,7 +210,7 @@ subroutine write_kmesh(common_data, istdout, istderr, ierr)
       return
     end if
 
-    if (mpirank(common_data%comm) == 0) then ! root only
+    if (mpirank(common_data%comm) == 0) then ! root only; no error condition
       call kmesh_write(common_data%exclude_bands, common_data%kmesh_info, &
                        common_data%select_proj%auto_projections, common_data%proj_input, &
                        common_data%print_output, common_data%kpt_latt, common_data%real_lattice, &