Improve file paths' documentation

[ScriBanana]

Hi,

Describe the bug
Importing a GAML file with an experiment makes it so you can run it from the both its definition and importing file. (Example : If I define an experiment "Run" in Experiment.gaml and use import "Experiment.gaml" in another file, I will have the button over both in the UI.)
The issue is that any relative path called in the model will depend on the file the button is pressed from.

To Reproduce
Build a file system like this :

├── Models
│   ├── Experiments
│   │   └── Experiment.gaml
│   └── Main.gaml
└── Utilities
    └── GenerateExportFiles.gaml

with main.gaml :

model Main
import "../Utilities/GenerateExportFiles.gaml"
import "Experiments/Experiments.gaml"

Experiment.gaml :

model Experiments
import "../Main.gaml"
experiment run;

GenerateExportFiles.gaml :

model GenerateExportFiles
global {
	string outputDirectory <- "../OutputFiles/";
	init {
		save "I am data!" to: outputDirectory + "Data.csv" type: csv rewrite: true;
	}
}

Here's the result after running the experiment both from Main.gaml and Experiment.gaml :

├── models
│   ├── Experiments
│   │   └── Experiments.gaml
│   ├── Main.gaml
│   └── OutputFiles
│       └── Data.csv
├── OutputFiles
│   └── Data.csv
└── Utilities
    └── GenerateExportFiles.gaml

Expected behavior
The OutputFiles directory being only created at the root of the project, at the location the path relative to where the save function was called from :

├── models
│   ├── Experiments
│   │   └── Experiments.gaml
│   └── Main.gaml
├── OutputFiles
│   └── Data.csv
└── Utilities
    └── GenerateExportFiles.gaml

Desktop (please complete the following information):

• OS: Manjaro Linux x86_64
• GAMA version: 1.8.2 RC2

I could simply not cross-import gaml files as a workaround, but it still looks like an issue.

[AlexisDrogoul]

Actually, this organisation is more a feature than an issue, although I can understand why it might generate difficulties. It has been done so that support files and experiments could easily be defined together (so if you have relative paths in your model to access support files, the ones defined with the current experiment will be used).

[ScriBanana]

Hi Alexis,
Alright, I see that being useful in that use case. It makes sense when explained. Maybe it deserves an explanation in the documentation to avoid confusion like mine ?

[AlexisDrogoul]

You are right. It definitely deserves a more detailed explanation somewhere... Let us ask @RoiArthurB where it could go in the documentation 🤔 ...

[ScriBanana]

I would suggest (if I may) at least a mention in https://gama-platform.org/wiki/DefiningExportFiles#facets, since it is the first time a newcomer would encounter using a path when reading the documentation.

[RoiArthurB]

Hi @ScriBanana

Sorry for the delayed answered (didn't saw the notification on this issue). Actually the documentation already explained this behavior here : https://gama-platform.org/wiki/ModelOrganization

But I agree that this little part is a bit difficult to spot. I'll add a part title so it can be catched by the search engine as well as a reminder at the location you pointed (as I guess you're a new comer with this software, I'll follow your logic for finding informations ;) )

I'll just ping @lesquoyb to know if you have some other enhancement idea about this point on the documentation :)

---

EDIT: Just to be clear, this relative path issue only exists within the GAML code; i.e. It doesn't happen with nested gaml file import (on the top of the file).

[lesquoyb]

Not sure about the documentation, but it could be nice to have a few statements to get the current file's path, the experiment file's path, directories and maybe others, so users can compose paths relative to what they think makes more sense. Like:

string embedded_file_path <- current_file_directory + "../includes/framework_file.png";
string custom_file_path <- experiment_file_directory + "../includes/my_file,png"

[hqnghi88]

@lesquoyb we already have project_path or experiment.project_path

[ScriBanana]

Hi @RoiArthurB, hi all,

Thanks, although I am very unsure that the documentation makes things clear enough as of yet, to be honest.

Let me reformulate what I understood :

• Statements are defined in the order they are read, i.e. in which they are imported. (The page you linked earlier)
• The order of definition of models depend not on where the called experiment is defined, but on which file it is called from, using the green button.
• Relative path in a statement will depend not on the file it is defined in, but on where the model is run from (i.e. where you pressed the green button from). So if main.gaml imports experiments.gaml and I press the button of an experiment defined in the former, all relative paths defined in variables will refer to main.gaml, regardless of where they are defined.
• However, relative path in an import statement will always relate to the current file location. In my example tree above, if I import "../Utilities/GenerateExportFiles.gaml" in main.gaml, this will always lead to the file, regardless on if I pressed the button in main.gaml or experiments.gaml.

So two things I failed to understand, that had me confused :

• The discrepancy between the last two statements. I am used to inputting relative path in import statements, which never change and always start from the importing file itself. Now, when I use a relative path inside a statement in a model definition (in a variable) the behaviour changed seemingly unexpectedly and now the path is relative to the caller file.
• The order in which files are imported depends on where the button is pressed from, not on where the experiment is defined, which is a bit confusing (could be mentioned here, for example).

So yes, maybe a section dedicated to what happens in what order when an execution is launched would make things clearer. Possibly as a complement to https://gama-platform.org/wiki/next/RuntimeConcepts ?

Either way, thanks for the clarification, it appears clear to me now.

[RoiArthurB]

A short explanation of this behavior has been added on the page https://github.com/gama-platform/gama/wiki/ModelOrganization as a note while describing how to import files, as well as in https://github.com/gama-platform/gama/wiki/DefiningExportFiles as a reminder while saving data with relative paths.

So yes, maybe a section dedicated to what happens in what order when an execution is launched would make things clearer. Possibly as a complement to https://gama-platform.org/wiki/next/RuntimeConcepts ?

I would disagree to add this point on this page as it's an overview of the main steps for creating a simulation and the scheduling of agents inside. I'm not sure that it's relevant to add information about how path are processed while exporting data there.

---

Considering this issue closed now, feel free to reopen if you consider some other places might be relevant :)