{"id":22282148,"url":"https://github.com/genericmappingtools/gmt-fortran","last_synced_at":"2026-01-06T02:35:39.150Z","repository":{"id":78848344,"uuid":"164029736","full_name":"GenericMappingTools/gmt-fortran","owner":"GenericMappingTools","description":"GMT API for FORTRAN","archived":false,"fork":false,"pushed_at":"2019-01-03T23:05:58.000Z","size":3191,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-30T16:58:38.108Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Fortran","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GenericMappingTools.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-03T22:34:21.000Z","updated_at":"2024-01-10T07:25:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"095bb47d-cd16-4f30-9832-6fd528d344f5","html_url":"https://github.com/GenericMappingTools/gmt-fortran","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmt-fortran","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmt-fortran/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmt-fortran/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmt-fortran/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GenericMappingTools","download_url":"https://codeload.github.com/GenericMappingTools/gmt-fortran/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245527632,"owners_count":20630062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T16:25:48.319Z","updated_at":"2026-01-06T02:35:39.104Z","avatar_url":"https://github.com/GenericMappingTools.png","language":"Fortran","readme":"$Id$\n\nGMT Fortran API README\n======================\n\nQuick howto\n-----------\nUsing GMT5 API calls from Fortran codes can be set up with help of a Fortran program unit \"module gmt\". By attaching the module, a Fortran user receives access to GMT C API enumerations, structures and interfaces, and also to Fortran wrappers that make calls to the C functions easier; in particular, the iso_c_binding module can remain behind the scene. The interfaces of the Fortran wrappers are largely simplified by means of optional arguments, and the wrappers also alleviate the transfer of character arguments. Finally, a couple of Fortran subroutines is available to facilitate transfer of Fortran user arrays into GMT5 data structures.\n\nAnother module with miscellaneous procedures (not needed but useful) for GMT Fortran API is \"module gmt_misc\". It should help especially to convert shell scripts to Fortran codes, especially to construct GMT module arguments by providing overloaded operators + and - for string concatenation with the trim feature, ability to concatenate strings with integer and real numbers and optional blank separation. Subroutines for echoing data to temporary files and removing the files supplied.\n\nGet the modules by\n\n\tsvn checkout svn://gmtserver.soest.hawaii.edu/gmt-fortran gmt-fortran\n\nand find both in gmt-fortran/trunk/src.\n\nAccess it from your Fortran source code as in, e.g.,\n\n\tuse gmt\n\tcall sGMT_Create_Session(\"Test\")\n\tcall sGMT(\"psxy file.dat -J -R -B -\u003efile.ps\")\n\tcall sGMT_Destroy_Session()\n\tend program\n\nor, with input data taken from arrays, as in\n\n\tuse gmt\n\tinteger,parameter :: nmax=3\n\treal(8) :: x(nmax)=[1,2,3],y(nmax)=[1,2,1]\n\tinteger(8) :: dim(2)=[2,nmax]\n\tcharacter(20) :: filedat,fileps=\"file.ps\"\n\tcall sGMT_Create_Session(\"Test\")\n\tcall sGMT_Create_Init_Encode(dim=dim,c1=x,c2=y,object_ID=id,string=filedat)\n\tcall sGMT(\"psxy \"//filedat//\" -JX8c -R0/4/0/3 -BWS+tFig. -Bx2+lx -By1+ly -Sa1c -\u003e\"//fileps)\n\tcall sGMT_Destroy_Session()\n\tend program\n\nCompile by Fortran compilers with the iso_c_binding support by commands similar to, e.g.,\n\n\tf90 gmt.f90 my_GMT_code.f90 -Lpath-to-gmt5-lib -lgmt\n\nTested with GNU, Intel, PGI and g95 on Linux and Windows, expected to work with many other compilers, cf.\n\n\thttp://fortranwiki.org/fortran/show/Fortran+2003+status\n\nCheck API examples of matching shell scripts, C codes and Fortran codes received along with the gmt.f90 in\n\n\tgmt-fortran/trunk/src/examples-api\n\tgmt-fortran/trunk/src/examples-openmp\n\tgmt-fortran/trunk/src/examples-share-doc\n\nLook at and send feedback to\n\n\thttp://gmt.soest.hawaii.edu/projects/gmt-fortran-api\n\nEnjoy.\n\nMore on the gmt module\n----------------------\nThe Fortran module gmt consists of (1) Fortran wrapper subroutines and functions to C API functions, (2) initialization subroutines to hide explicit data transfer between user arrays and C API structures and (3) interfaces to the C API functions; moreover, C API (4) enumerations and (5) structures are ported to the module as well.\n\n(1) The high-level wrappers with simplified interface and many optional arguments hide most of interoperability tricks from the Fortran user. The wrappers have the form of both subroutines (sGMT_*) and equivalent functions (GMT_*). The most frequent C API function GMT_Call_Module can be called via super-wrappers sGMT, fGMT or GMTF. The most frequent C API argument that denotes the GMT session is optional and defaults to an internal module pointer.\nExamples of wrapper subroutines and functions: \n\n\tcall sGMT_Create_Session(\"Test\")\n\tcall sGMT(\"psxy file.dat -J -R -B -\u003efile.ps\")\n\tcall sGMT_Destroy_Session()\n\n\terr=GMT_Create_Default_Session(\"Test\")\n\terr=fGMT(\"ps2raster file.ps -Tg\")\n\terr=GMT_Destroy_Session()\n\n(2) Initialization subroutines (sGMTF_*, with aliases sGMT_*) facilitate data transfer from Fortran user arrays to GMT structures. At present, subroutines for data transfer to GMT_VECTOR structures are available. Subroutines to populate GMT_MATRIX structures are other candidates to emerge. \nExample how to create, initialize and encode type(GMT_VECTOR) v from user arrays x, y:\n\ttype(c_ptr) v; integer(8) dim(2); real(8) x(nmax),y(nmax); integer id; character(16) file\n\tv=GMT_Create_Data(dim=dim)\n\tcall sGMTF_Init_Vector(resource=v,c1=x,c2=y)\n\tid=GMT_Get_ID(resource=v)\n\tcall sGMT_Encode_ID(string=file,object_ID=id)\nor by a single cumulative call:\n\tcall sGMTF_Create_Init_Encode(dim=dim,c1=x,c2=y,object_ID=id,string=file)\n\n(3) Interfaces to C API functions are also available and can be used via cGMT_* function calls. Explicit references to the iso_c_binding machinery are necessary that makes the cGMT_* functions rather low-level.\nExample:\n\ttype(c_ptr) API\n\tAPI=cGMT_Create_Session(\"Test\"//c_null_char,2,0,0)\n\terr=cGMT_Call_Module(API,\"psxy\"//c_null_char,GMT_MODULE_CMD,\"file.dat -J -R -B -\u003efile.ps\"//c_null_char)\n\terr=cGMT_Destroy_Session(API)\n\n(4) All enumerated integer constants from the C API header files are available, e.g., GMT_IS_DATASET, GMT_IS_POINT, GMT_MODULE_CMD and hundreds of others. They are mostly intended to modify the default behavior of GMT API functions via optional arguments. Few of them differ from the C function names by the letter case only; in such cases, the enumerated constants are renamed on the Fortran side (GMT_DUPLICATE_DATA_ENUM, GMT_OPTION_STRUCT, k/kk).\n\n(5) Many structure definitions from the C API header files are made interoperable with Fortran, e.g., GMT_VECTOR, GMT_MATRIX and GMT_DATASET. They can be used for importing data from user arrays into GMT API structures with the help of iso_c_binding techniques. Often, auxiliary Fortran subroutines sGMTF_* may alleviate these steps. Note that there is no need to seek for an interoperable counterpart to C unions (e.g., GMT_UNIVECTOR); the approach based on assignment statements with help of the iso_s_binding c_loc function can be found in the sGMTF_Init_Vector_* series of Fortran subroutines.\n\nGMT Fortran wrapper subroutines\n-------------------------------\nAll wrapper subroutines have the name pattern sGMT_*. They keep all the arguments of the original C API functions, however, some are optional and some may have other data types more appropriate to Fortran users. Subroutine sGMT is a super-wrapper to GMT_Call_Module. The wrappers handle the transfer of Fortran character arguments to C functions via trim(string)//c_null_char (zero-terminated strings of dynamic length). The wrappers also provide default values to non-present optional arguments. The first argument (eAPI) of all wrappers denotes the API session and, if omitted, it defaults to an internal pointer (iAPI). With the first argument not present, the other arguments must be passed via the keyword (not positional) association, e.g., call sGMT_Call_Module(module=module,args=args). The super-wrapper sGMT accepts the non-keyword association of the cmd argument, e.g., call sGMT(eAPI,cmd); call sGMT(cmd).\n\nList of sGMT_* subroutines\nsubroutine sGMT_Create_Session(tag[,pad][,mode][,print_func][,eAPI][,err])\n\tcharacter(*) tag; type(c_ptr) eAPI; integer err\n\tdefaults: pad=2; mode=0; print_func=0; eAPI=iAPI\nsubroutine sGMT_Call_Module([eAPI,]module[,mode],args[,err])\n\tcharacter(*) module,args\n\tdefaults: eAPI=iAPI; mode=GMT_MODULE_CMD\nsubroutine sGMT([eAPI,]cmd[,err]); subroutine sGMT(cmd[,err]) - a super-wrapper to GMT_Call_Module\n\ttype(c_ptr) eAPI; character(*) cmd\n\tnote: positional association is possible, i.e., can be referenced via both call sGMT(cmd=cmd) and call sGMT(cmd)\nsubroutine sGMT_Destroy_Session([eAPI,][err])\nsubroutine sGMT_Create_Data([eAPI,][family,][geometry,][mode,]dim[,wesn][,inc][,registration][,pad][,data],resource[,err])\n\tinteger(8) dim(2); type(c_ptr) resource; real(8) wesn(6),inc(2)\n\tdefaults: family=GMT_IS_VECTOR; geometry=GMT_IS_POINT; mode=0; wesn=c_null_ptr; inc=c_null_ptr; registration=0; pad=0; data=c_null_ptr\n\tnote: non-default kind of the integer array dim(2)\nsubroutine sGMT_Get_Data([eAPI,]object_ID[,mode][,data],resource[,err])\n\tinteger object_ID; type(c_ptr) resource\n\tdefaults: mode=0; data=c_null_ptr\nsubroutine sGMT_Read_Data([eAPI,][family,][method,][geometry,][mode,][wesn,]input[,data],resource[,err])\n\tcharacter(*) input; type(c_ptr) resource\n\tdefaults: family=GMT_IS_VECTOR; method=GMT_IS_FILE; geometry=GMT_IS_POINT; mode=0; wesn=c_null_ptr; data=c_null_ptr\nsubroutine sGMT_Retrieve_Data([eAPI,]object_ID,resource[,err])\n\tinteger object_ID; type(c_ptr) resource\nsubroutine sGMT_Duplicate_Data([eAPI,][family,][mode,]data,resource[,err])\n\ttype(c_ptr) data,resource\n\tdefaults: family=GMT_IS_GRID; mode=GMT_DUPLICATE_DATA_ENUM (C API value: GMT_DUPLICATE_DATA)\nsubroutine sGMT_Put_Data([eAPI,]object_ID[,mode],data[,err])\n\tinteger oject_ID; type(c_ptr) data\n\tdefaults: mode=GMT_IS_GRID\nsubroutine sGMT_Write_Data([eAPI,][family,][method,][geometry,][mode,][wesn,]output,data[,err])\n\tcharacter(*) output; type(c_ptr) data\n\tdefaults: family=GMT_IS_GRID; method=GMT_IS_FILE; geometry=GMT_IS_SURFACE; mode=GMT_GRID_ALL; wesn=c_null_ptr\nsubroutine sGMT_Register_IO([eAPI,][family,][method,][geometry,][direction,][wesn,][resource,]object_ID)\n\ttype(c_ptr) resource; integer object_ID\n\tdefaults: family=GMT_IS_DATASET; method=GMT_IS_FILE; geometry=GMT_IS_POINT; direction=GMT_IN; wesn=c_null_ptr; resource=c_null_ptr\nsubroutine sGMT_Register_IO_char([eAPI,][family,][method,][geometry,][direction,][wesn,]resource,object_ID)\n\tcharacter(*) resource; integer object_ID\n\tdefaults: family=GMT_IS_DATASET; method=GMT_IS_FILE; geometry=GMT_IS_POINT; direction=GMT_IN; wesn=c_null_ptr\nsubroutine sGMT_Init_IO([eAPI,][family,][geometry,][direction,][mode,][n_args,][args,][err])\n\tdefaults: family=GMT_IS_DATASET; geometry=GMT_IS_POINT; direction=GMT_IN; mode=GMT_ADD_DEFAULT; n_args=0; args=c_null_ptr\nsubroutine sGMT_Encode_ID([eAPI,]string,object_ID[,err])\n\tcharacter(16) string; integer object_ID\nsubroutine sGMT_Get_ID([eAPI,][family,][direction,]resource,object_ID[,err])\n\ttype(c_ptr) resource; integer object_ID\n\tdefaults: family=GMT_IS_DATASET; direction=GMT_IN\nsubroutine sGMT_Report([eAPI,][level,]message[,err])\n\tcharacter(*) message\n\tdefaults: level=GMT_MSG_NORMAL\nsubroutine sGMT_Message([eAPI,][mode,]format[,err])\n\tcharacter(*) format\n\tdefaults: mode=GMT_TIME_NONE\n\nGMT Fortran wrapper functions\n-----------------------------\nThe name pattern: GMT_*. The functions have the same interface as the subroutine counterparts; exceptions are the return values. One new wrapper function is added to create a default session without explicit assignment of the eAPI pointer. Super-wrapper functions to GMT_Call_Module received synonymous names fGMT and GMTF (simple \"GMT\" is reserved as a module name). Optional arguments and default values in the wrapper functions are the same as in the wrapper subroutines. \n\nList of GMT_* functions\ntype(c_ptr) function GMT_Create_Session(tag,pad,mode,print_func,err)\ninteger function GMT_Create_Default_Session(tag,pad,mode,print_func) - to create a default session\ninteger function GMT_Call_Module(eAPI,module,mode,args)\ninteger function fGMT([eAPI,]cmd); integer function fGMT(cmd) - a super-wrapper to GMT_Call_Module\ninteger function GMTF([eAPI,]cmd); integer function GMTF(cmd) - a super-wrapper to GMT_Call_Module\ninteger function GMT_Destroy_Session(eAPI)\ntype(c_ptr) function GMT_Create_Data(eAPI,family,geometry,mode,dim,wesn,inc,registration,pad,data,err)\ntype(c_ptr) function GMT_Get_Data(eAPI,object_ID,mode,data,err)\ntype(c_ptr) function GMT_Read_Data(eAPI,family,method,geometry,mode,wesn,input,data,err)\ntype(c_ptr) function GMT_Retrieve_Data(eAPI,object_ID,err)\ntype(c_ptr) function GMT_Duplicate_Data(eAPI,family,mode,data,err)\ninteger function GMT_Put_Data(eAPI,object_ID,mode,data)\ninteger function GMT_Write_Data(eAPI,family,method,geometry,mode,wesn,output,data)\ninteger function GMT_Register_IO(eAPI,family,method,geometry,direction,wesn,resource)\ninteger function GMT_Register_IO_char(eAPI,family,method,geometry,direction,wesn,resource)\ninteger function GMT_Init_IO(eAPI,family,geometry,direction,mode,n_args,args)\ninteger function GMT_Encode_ID(eAPI,string,object_ID)\ninteger function GMT_Get_ID(eAPI,family,direction,resource,err)\ninteger function GMT_Report(eAPI,level,message)\ninteger function GMT_Message(eAPI,mode,format)\n\nFortran subroutines for initialization of C structs\n---------------------------------------------------\nThe name pattern: sGMTF_*, also aliased to sGMT_*. Overloaded for real(4)/real(8) 1D/2D array arguments c1, ..., c5.\n\nList of generic sGMTF_* subroutines\nsubroutine sGMTF_Init_Vector([eAPI,]resource,c1[,c2][,c3][,c4][,c5])\n\ttype(c_ptr) resource; real(4|8),dimension(*|1,*) c1,c2,c3,c4,c5\nsubroutine sGMTF_Create_Init_Encode \u0026\n\t([eAPI,][family,][geometry,][mode,]dim,[wesn,][inc,][registration,][pad,][data,]c1[,c2][,c3][,c4][,c5],object_ID,string)\n\ttype(c_ptr) resource; real(4|8),dimension(*|1,*) c1,c2,c3,c4,c5\n\tdefaults: as in sGMT_Create_Data (can be changed) and sGMT_Get_ID (fixed values)\n\nList of specific sGMTF_* subroutines\nsGMTF_Init_Vector_r4_1D,sGMTF_Init_Vector_r4_2D,sGMTF_Init_Vector_r8_1D,sGMTF_Init_Vector_r8_2D\nsGMTF_Create_Init_Encode_r4_1D,sGMTF_Create_Init_Encode_r4_2D,sGMTF_Create_Init_Encode_r8_1D,sGMTF_Create_Init_Encode_r8_2D\n\nInterfaces to C functions\n-------------------------\nThe name pattern: cGMT_*. Required all arguments as described in the GMT C API documentation. Several iso_c_binding tricks are necessary to maintain the correct functionality. E.g., Fortran strings passed to the cGMT_* functions have to be zero-terminated and sometimes the trimming is necessary:\n\terr=cGMT_Call_Module(API,trim(module)//c_null_char,GMT_MODULE_CMD,trim(args)//c_null_char)\nor C strings returned to the Fortran side might need to have the '\\0' character removed, as is the case of the string argument after a call to cGMT_Encode_ID; cGMT_Report and cGMT_Message functions expect receiving string arguments ended with c_new_line//c_null_char. Frequent calls to the c_loc, c_f_pointer and c_associated procedures might be necessary in many contexts.\n\nList of cGMT_* functions\ncGMT_Create_Session, cGMT_Call_Module, cGMT_Destroy_Session, cGMT_Create_Data, cGMT_Get_Data, cGMT_Read_Data, cGMT_Retrieve_Data, cGMT_Duplicate_Data, sGMT_Put_Data, sGMT_Write_Data, cGMT_Register_IO, cGMT_Init_IO, cGMT_Encode_ID, cGMT_Get_ID, cGMT_Report, cGMT_Message\nand all others as specified in the GMT API Documentation.\n\nTechnical notes\n---------------\n- Encode_ID is Fortran-native, without a call to C API\n- Destroy_Session nullifies API pointer\n- merge(opt,dummy,present(opt)) can make segfault in PGI\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenericmappingtools%2Fgmt-fortran","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenericmappingtools%2Fgmt-fortran","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenericmappingtools%2Fgmt-fortran/lists"}