Before we merge this -- I think we need to have a consensus on changes in this direction -- not sure we have this yet, and it is silly for folks to do work to change things back and forth.

@projectmesa/maintainers please everyone let know your preference to which kind of paper you want:

1. An update paper, like the previous version in #2533.
2. An present state paper, like proposed here.
3. Something else.

I'm indifferent, both have their merit.

I am in favor of option 2 (as might have been clear from my review of #2533).

I have been chewing on this the few days since the #2533 debate started. I suppose what I want to propose is hybrid.

• I think Mesa 3 needs to be in the title and the summary should explicitly state this overviews Mesa 3. I would also remove the granularity of Mesa 3.1.1 as I imagine the next paper will be Mesa 4. I would also explicitly reference the previous 2 papers in the summary.
• I would then not belabor that fact that this is Mesa 3, in the Core Capabilities section I would keep them pretty much the same and not show as a constant update between 2 and 3 but just how one "Mesas"

Why:

1. To @wang-boyu point this will make it explicit to existing users there is a change, while allowing new users to quickly register this is Mesa 3 but really just focus on implementing Mesa without the additional cognitive load of 2 to 3.

2. I not sure how much this will move the needle, but we need increase the explicit digital trail that Mesa 3 is different to update the LLMs. People use LLMs for code all the time and right now they still predominantly provide mesa.schedule.agents . Therefore, just for an anecdotal assessment of the impact on LLMs and the reality that we need to create explicit Mesa 3 items in the digital world to help folks and LLMs differentiate.

Thanks for your feedback Tom.

I think Mesa 3 needs to be in the title and the summary should explicitly state this overviews Mesa 3.

Agreed, and this is currently already the case.

I would also remove the granularity of Mesa 3.1.1

Personally I think it's nice to be explicit about it. Maybe just say 3.1.

I would also explicitly reference the previous 2 papers in the summary.

Will do

I would then not belabor that fact that this is Mesa 3, in the Core Capabilities section I would keep them pretty much the same and not show as a constant update between 2 and 3 but just how one "Mesas"

Agreed. With this PR, that is currently the case right?

As of LLMs, this will keep being a problem as long as they don't take in . Just advice anyone to upload getting_started.md and migration_guide.md whenever using an LLM. Optionally, also add agent.py and model.py. With that, it works perfectly in my experience.

It looks like there's a small nudge towards options 2:

1. Jan is (strongly) in favor
2. Tom proposed a hybrid nudging towards option 2, and Wang "thumbs up" on that
3. Jackie is against
4. I'm indifferent

@projectmesa/maintainers I would like some explicit reviews on this PR: Either green checkmarks or concrete comments/suggestions.

I think Mesa 3 needs to be in the title and the summary should explicitly state this overviews Mesa 3. I would also remove the granularity of Mesa 3.1.1 as I imagine the next paper will be Mesa 4. I would also explicitly reference the previous 2 papers in the summary.

I haven't seen any papers in JOSSS with the version number in the title which is why I adviced to remove it from the title. I agree that we should mention very early that this paper reflects mesa 3 and then just move on and talk about MESA as such.

not sure how much this will move the needle, but we need increase the explicit digital trail that Mesa 3 is different to update the LLMs.

I don't think it will move the needle at all. what is needed is to have more mesa 3 examples, new LLMs trained on more recent code bases, and the work around @EwoutH suggested.

@projectmesa/maintainers I would like some explicit reviews on this PR: Either green checkmarks or concrete comments/suggestions.

On it, hope to have a bunch of suggestions soon. Do you mind if I commit directly, or do you prefer me using github's suggestion feature?

Summary and statement of need are fine with some minor possible language fixes (comma stuff).

I like the restructuring. It reads a lot nicer now.

I personally would expand the start on core ABM components a bit along the lines I suggested before. So, give a 1 paragraph description of what ABM modeling is and make sure we mention agents, agent activation, and environment. Next, we can introduce Agents, Agent activation via agentsets, and representing the environment (I prefer this phrasing over spatial modeling which might easily be misunderstood). I noticed that the grid stuff is still about the old style grids. Is this a deliberate choice? I am happy to make these changes if you want somewhere over the coming week.

Likewise, I would flesh out the visualization and experimentation part a bit more. Again, I can take a stab at this if desired. For example, it would be good to add that the UI uses Solara with a reference to this library and a short 1 or 2 sentence elaboration that this means that users can build web based UIs that are either stand alone or can be used within a jupyter notebook. Likewise, I would elaborate briefly on the parameter sweeps by stating that this supports full factorial sampling, seed control, and (limited) support for parallelization. Next, in a few sentences we can elaborate that other python libraries can be used if more sophisticated sampling is required.

What is the plan regarding adding citations?

Thanks for your thoughts!

I like the restructuring. It reads a lot nicer now.

Great to hear!

What is the plan regarding adding citations?

References can go into paper/paper.bib. We can add them using (see JOSS manual):

Cite a bibliography entry by referencing its identifier: [@upper1974] will create the reference “(Upper 1974)”. Omit the brackets when referring to the author as part of a sentence: “For a case study on writers block, see Upper (1974).” Please refer to the pandoc manual for additional features, including page locators, prefixes, suffixes, and suppression of author names in citations.

On it, hope to have a bunch of suggestions soon. Do you mind if I commit directly, or do you prefer me using github's suggestion feature?

I think most practical is I merge this PR, since we seem to agree this moves the paper in the right direction. Then you can propose your changes in a new PR to the paper_2024 branch.

I think most practical is I merge this PR, since we seem to agree this moves the paper in the right direction. Then you can propose your changes in a new PR to the paper_2024 branch.

Yes that workflow makes good sense to me.

Merged, go ahead!