[gmx-developers] GMX library functions and documentation

[Mark Abraham]

On 15/09/2012 12:14 AM, Ondrej Marsalek wrote:
> Hi,
>
> I am writing an analysis tool and I am having some trouble using the
> GMX library functions or finding documentation for them. I am
> currently working against 4.5.3. Is there some kind of comprehensive
> documentation? It seems that the Doxygen documentation make targets
> mentioned on the web do not exist in 4.5.3. Should I just read the
> code?

Unfortunately the best approach available is to look around at what 
existing tools do and pick one/several that have a similar mode of 
operation and derive from that. Hopefully things will improve a lot in 
the transition to GROMACS 5, but that is some (man-)years away yet.

> One specific problem that I have is with output_env_t. I have found
> these two functions:
>
> output_env_init
> output_env_init_default
>
> and as I have no specific requirements, I just wanted to use the
> second one, at the very beginning of my program. However, it
> segfaults:
>
> ==21076== Process terminating with default action of signal 11 (SIGSEGV)
> ==21076==  Bad permissions for mapped region at address 0x4096E0
> ==21076==    at 0x56B4C85: output_env_init (oenv.c:96)
> ==21076==    by 0x56B4E92: output_env_init_default (oenv.c:143)
> ==21076==    by 0x403049: main (ctcf.c:483)
>
> Checking all the analysis tools, I don't see a single use of any of
> these two functions, although the output environment is used. Should I
> just use it uninitialized?

I've never needed to know. I suggest you copy the kind of thing that 
other tools do.

> There are some small things that I have encountered as well.
> Inconsistent naming: output_env_t vs t_trxstatus.

These do different things. Not sure what you mean.

>   Inconsistent
> arguments: read_first_x wants trxstatus**, while read_next_x and
> close_trj want trxstatus*.

Generally, functions with names matching *first* might allocate memory, 
so they need the address of a pointer to store. Later functions just 
need the pointer to use.

Mark